System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 8b197607851af8620ea1eb4a4203c3679966a00e:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 37 2e 31 36 2e 20 20  ersion 3.7.16.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e  atic.#endif.#ifn
0550: 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23  def SQLITE_API.#
0560: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41   define SQLITE_A
0570: 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a  PI.#endif./*****
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20  ********* Begin 
0590: 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68  file sqliteInt.h
05a0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20  ********/./*.** 
05d0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31  2001 September 1
05e0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  5.**.** The auth
05f0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70  or disclaims cop
0600: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73  yright to this s
0610: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20  ource code.  In 
0620: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65  place of.** a le
0630: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65  gal notice, here
0640: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a   is a blessing:.
0650: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  **.**    May you
0660: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74   do good and not
0670: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79   evil..**    May
0680: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76   you find forgiv
0690: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65  eness for yourse
06a0: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f  lf and forgive o
06b0: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79  thers..**    May
06c0: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c   you share freel
06d0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20  y, never taking 
06e0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69  more than you gi
06f0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ve..**.*********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0740: 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74  .** Internal int
0750: 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f  erface definitio
0760: 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a  ns for SQLite..*
0770: 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51  *.*/.#ifndef _SQ
0780: 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69  LITEINT_H_.#defi
0790: 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f  ne _SQLITEINT_H_
07a0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64  ../*.** These #d
07b0: 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e  efines should en
07c0: 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73  able >2GB file s
07d0: 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20  upport on POSIX 
07e0: 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  if the.** underl
07f0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
0800: 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69  ystem supports i
0810: 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61  t.  If the OS la
0820: 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c  cks.** large fil
0830: 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66  e support, or if
0840: 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f   the OS is windo
0850: 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64  ws, these should
0860: 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   be no-ops..**.*
0870: 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20  * Ticket #2739: 
0880: 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f   The _LARGEFILE_
0890: 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73  SOURCE macro mus
08a0: 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20  t appear before 
08b0: 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69  any.** system #i
08c0: 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c  ncludes.  Hence,
08d0: 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63   this block of c
08e0: 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20  ode must be the 
08f0: 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f  very first.** co
0900: 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65  de in all source
0910: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61   files..**.** La
0920: 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74  rge file support
0930: 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64   can be disabled
0940: 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c   using the -DSQL
0950: 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20  ITE_DISABLE_LFS 
0960: 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65  switch.** on the
0970: 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e   compiler comman
0980: 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73  d line.  This is
0990: 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f   necessary if yo
09a0: 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a  u are compiling.
09b0: 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d  ** on a recent m
09c0: 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20  achine (ex: Red 
09d0: 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75  Hat 7.2) but you
09e0: 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20   want your code 
09f0: 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e  to work.** on an
0a00: 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28   older machine (
0a10: 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29  ex: Red Hat 6.0)
0a20: 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c  .  If you compil
0a30: 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32  e on Red Hat 7.2
0a40: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73  .** without this
0a50: 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20   option, LFS is 
0a60: 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53  enable.  But LFS
0a70: 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20   does not exist 
0a80: 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a  in the kernel.**
0a90: 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c   in Red Hat 6.0,
0aa0: 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e   so the code won
0ab0: 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c  't work.  Hence,
0ac0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e   for maximum bin
0ad0: 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69  ary.** portabili
0ae0: 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d  ty you should om
0af0: 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 69  it LFS..**.** Si
0b00: 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f  milar is true fo
0b10: 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53  r Mac OS X.  LFS
0b20: 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74   is only support
0b30: 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39  ed on Mac OS X 9
0b40: 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23   and later..*/.#
0b50: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49  ifndef SQLITE_DI
0b60: 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69  SABLE_LFS.# defi
0b70: 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20  ne _LARGE_FILE  
0b80: 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20       1.# ifndef 
0b90: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54  _FILE_OFFSET_BIT
0ba0: 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49  S.#   define _FI
0bb0: 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36  LE_OFFSET_BITS 6
0bc0: 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69  4.# endif.# defi
0bd0: 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f  ne _LARGEFILE_SO
0be0: 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f  URCE 1.#endif../
0bf0: 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65  *.** Include the
0c00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 68   configuration h
0c10: 65 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 20  eader output by 
0c20: 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 77  'configure' if w
0c30: 65 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  e're using the.*
0c40: 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 64  * autoconf-based
0c50: 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 66   build.*/.#ifdef
0c60: 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 4f   _HAVE_SQLITE_CO
0c70: 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 20  NFIG_H.#include 
0c80: 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 69  "config.h".#endi
0c90: 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  f../************
0ca0: 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74  ** Include sqlit
0cb0: 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 20  eLimit.h in the 
0cc0: 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65  middle of sqlite
0cd0: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  Int.h **********
0ce0: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
0cf0: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71  ** Begin file sq
0d00: 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a  liteLimit.h ****
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d30: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d 61  */./*.** 2007 Ma
0d40: 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  y 7.**.** The au
0d50: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
0d60: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
0d70: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
0d80: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0d90: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0da0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0db0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0dc0: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0dd0: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0de0: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0df0: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0e00: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0e10: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0e20: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
0e30: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
0e40: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
0e50: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ea0: 2a 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 66  **.** .** This f
0eb0: 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 69  ile defines vari
0ec0: 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 68  ous limits of wh
0ed0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 72  at SQLite can pr
0ee0: 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ocess..*/../*.**
0ef0: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   The maximum len
0f00: 67 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f 72  gth of a TEXT or
0f10: 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 20   BLOB in bytes. 
0f20: 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 6c    This also.** l
0f30: 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f  imits the size o
0f40: 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 62  f a row in a tab
0f50: 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a 0a  le or index..**.
0f60: 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d 69  ** The hard limi
0f70: 74 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 79  t is the ability
0f80: 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
0f90: 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 74  ned integer.** t
0fa0: 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a 65  o count the size
0fb0: 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 37  : 2^31-1 or 2147
0fc0: 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 64  483647..*/.#ifnd
0fd0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  ef SQLITE_MAX_LE
0fe0: 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51  NGTH.# define SQ
0ff0: 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 20  LITE_MAX_LENGTH 
1000: 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 69  1000000000.#endi
1010: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 73  f../*.** This is
1020: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1030: 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 20  ber of.**.**    
1040: 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  * Columns in a t
1050: 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c  able.**    * Col
1060: 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
1070: 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e 73  .**    * Columns
1080: 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 20   in a view.**   
1090: 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20   * Terms in the 
10a0: 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 6e  SET clause of an
10b0: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
10c0: 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20  t.**    * Terms 
10d0: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
10e0: 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
10f0: 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a 20  atement.**    * 
1100: 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 4f  Terms in the GRO
1110: 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 42  UP BY or ORDER B
1120: 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 53  Y clauses of a S
1130: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1140: 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69  .**    * Terms i
1150: 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61  n the VALUES cla
1160: 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54  use of an INSERT
1170: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
1180: 20 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20   The hard upper 
1190: 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 32  limit here is 32
11a0: 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 62  676.  Most datab
11b0: 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c 0a  ase people will.
11c0: 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 74  ** tell you that
11d0: 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d 61   in a well-norma
11e0: 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c 20  lized database, 
11f0: 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f 75  you usually shou
1200: 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 6d  ld.** not have m
1210: 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 6e  ore than a dozen
1220: 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 69   or so columns i
1230: 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 6e  n any table.  An
1240: 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 20  d if.** that is 
1250: 74 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 20  the case, there 
1260: 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 68  is no point in h
1270: 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aving more than 
1280: 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 76  a few.** dozen v
1290: 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 20  alues in any of 
12a0: 74 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 74  the other situat
12b0: 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61  ions described a
12c0: 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  bove..*/.#ifndef
12d0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55   SQLITE_MAX_COLU
12e0: 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  MN.# define SQLI
12f0: 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 30  TE_MAX_COLUMN 20
1300: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1310: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   The maximum len
1320: 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  gth of a single 
1330: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1340: 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 74   bytes..**.** It
1350: 20 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20   used to be the 
1360: 63 61 73 65 20 74 68 61 74 20 73 65 74 74 69 6e  case that settin
1370: 67 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f 20  g this value to 
1380: 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 75  zero would.** tu
1390: 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 66  rn the limit off
13a0: 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c 6f  .  That is no lo
13b0: 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 69  nger true.  It i
13c0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a 2a  s not possible.*
13d0: 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 6c  * to turn this l
13e0: 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 66  imit off..*/.#if
13f0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1400: 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 66  SQL_LENGTH.# def
1410: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53  ine SQLITE_MAX_S
1420: 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 30  QL_LENGTH 100000
1430: 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  0000.#endif../*.
1440: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  ** The maximum d
1450: 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 65  epth of an expre
1460: 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 73  ssion tree. This
1470: 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 0a   is limited to .
1480: 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62  ** some extent b
1490: 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c  y SQLITE_MAX_SQL
14a0: 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f 6d  _LENGTH. But som
14b0: 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 20  etime you might 
14c0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 63  .** want to plac
14d0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c 69  e more severe li
14e0: 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  mits on the comp
14f0: 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a 2a  lexity of an .**
1500: 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a 0a   expression..**.
1510: 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20  ** A value of 0 
1520: 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 61  used to mean tha
1530: 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
1540: 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a 2a  not enforced..**
1550: 20 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f 20   But that is no 
1560: 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 68  longer true.  Th
1570: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 73  e limit is now s
1580: 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 64  trictly enforced
1590: 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 73  .** at all times
15a0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
15b0: 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50  ITE_MAX_EXPR_DEP
15c0: 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  TH.# define SQLI
15d0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54  TE_MAX_EXPR_DEPT
15e0: 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f  H 1000.#endif../
15f0: 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d  *.** The maximum
1600: 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
1610: 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
1620: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1630: 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 6e  .** The code gen
1640: 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 6f  erator for compo
1650: 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1660: 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a 2a  ments does one.*
1670: 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 72  * level of recur
1680: 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 65  sion for each te
1690: 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 65  rm.  A stack ove
16a0: 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c 74  rflow can result
16b0: 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 65  .** if the numbe
16c0: 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 6f  r of terms is to
16d0: 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 61  o large.  In pra
16e0: 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c 0a  ctice, most SQL.
16f0: 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f 72  ** never has mor
1700: 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 65  e than 3 or 4 te
1710: 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c 75  rms.  Use a valu
1720: 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 6c  e of 0 to disabl
1730: 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 6f  e.** any limit o
1740: 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
1750: 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1760: 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a 23  unt SELECT..*/.#
1770: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41  ifndef SQLITE_MA
1780: 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  X_COMPOUND_SELEC
1790: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  T.# define SQLIT
17a0: 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53  E_MAX_COMPOUND_S
17b0: 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 66  ELECT 500.#endif
17c0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69  ../*.** The maxi
17d0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70  mum number of op
17e0: 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 20  codes in a VDBE 
17f0: 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 20  program..** Not 
1800: 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 63  currently enforc
1810: 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  ed..*/.#ifndef S
1820: 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f  QLITE_MAX_VDBE_O
1830: 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  P.# define SQLIT
1840: 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 35  E_MAX_VDBE_OP 25
1850: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  000.#endif../*.*
1860: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  * The maximum nu
1870: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
1880: 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e 63  s to an SQL func
1890: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  tion..*/.#ifndef
18a0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43   SQLITE_MAX_FUNC
18b0: 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 6e  TION_ARG.# defin
18c0: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e  e SQLITE_MAX_FUN
18d0: 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 65  CTION_ARG 127.#e
18e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  ndif../*.** The 
18f0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1900: 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 65  f in-memory page
1910: 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65  s to use for the
1920: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a 2a   main database.*
1930: 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 20  * table and for 
1940: 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 73  temporary tables
1950: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45  .  The SQLITE_DE
1960: 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45  FAULT_CACHE_SIZE
1970: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
1980: 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 45  TE_DEFAULT_CACHE
1990: 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53  _SIZE.# define S
19a0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41  QLITE_DEFAULT_CA
19b0: 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a 23  CHE_SIZE  2000.#
19c0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
19d0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 4d  LITE_DEFAULT_TEM
19e0: 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 64  P_CACHE_SIZE.# d
19f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
1a00: 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 5f  AULT_TEMP_CACHE_
1a10: 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 66  SIZE  500.#endif
1a20: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ../*.** The defa
1a30: 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 72  ult number of fr
1a40: 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c 61  ames to accumula
1a50: 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69  te in the log fi
1a60: 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 65  le before.** che
1a70: 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 64  ckpointing the d
1a80: 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d  atabase in WAL m
1a90: 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ode..*/.#ifndef 
1aa0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57  SQLITE_DEFAULT_W
1ab0: 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e  AL_AUTOCHECKPOIN
1ac0: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  T.# define SQLIT
1ad0: 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55  E_DEFAULT_WAL_AU
1ae0: 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 30  TOCHECKPOINT  10
1af0: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1b00: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   The maximum num
1b10: 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20  ber of attached 
1b20: 64 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 73  databases.  This
1b30: 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
1b40: 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 54   0.** and 62.  T
1b50: 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  he upper bound o
1b60: 6e 20 36 32 20 69 73 20 62 65 63 61 75 73 65 20  n 62 is because 
1b70: 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  a 64-bit integer
1b80: 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 73   bitmap.** is us
1b90: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
1ba0: 20 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 20   track attached 
1bb0: 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 69  databases..*/.#i
1bc0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1bd0: 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 69  _ATTACHED.# defi
1be0: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54  ne SQLITE_MAX_AT
1bf0: 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 66  TACHED 10.#endif
1c00: 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78  .../*.** The max
1c10: 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 20  imum value of a 
1c20: 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 68  ?nnn wildcard th
1c30: 61 74 20 74 68 65 20 70 61 72 73 65 72 20 77 69  at the parser wi
1c40: 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 69  ll accept..*/.#i
1c50: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1c60: 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1c70: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1c80: 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
1c90: 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 0a  MBER 999.#endif.
1ca0: 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 65  ./* Maximum page
1cb0: 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 65   size.  The uppe
1cc0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 20  r bound on this 
1cd0: 76 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e 20  value is 65536. 
1ce0: 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a 2a   This a limit.**
1cf0: 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 20   imposed by the 
1d00: 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f 66  use of 16-bit of
1d10: 66 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 63  fsets within eac
1d20: 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 61  h page..**.** Ea
1d30: 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  rlier versions o
1d40: 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 64  f SQLite allowed
1d50: 20 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 61   the user to cha
1d60: 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 61  nge this value a
1d70: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t.** compile tim
1d80: 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c 6f  e. This is no lo
1d90: 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c 20  nger permitted, 
1da0: 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 74  on the grounds t
1db0: 68 61 74 20 69 74 20 63 72 65 61 74 65 73 0a 2a  hat it creates.*
1dc0: 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 74  * a library that
1dd0: 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 20   is technically 
1de0: 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 74  incompatible wit
1df0: 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 72  h an SQLite libr
1e00: 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  ary .** compiled
1e10: 20 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e   with a differen
1e20: 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 72  t limit. If a pr
1e30: 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 20  ocess operating 
1e40: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  on a database .*
1e50: 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 69  * with a page-si
1e60: 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 65  ze of 65536 byte
1e70: 73 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e 20  s crashes, then 
1e80: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 53  an instance of S
1e90: 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 6c  QLite .** compil
1ea0: 65 64 20 77 69 74 68 20 74 68 65 20 64 65 66 61  ed with the defa
1eb0: 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c 69  ult page-size li
1ec0: 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  mit will not be 
1ed0: 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b  able to rollback
1ee0: 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 64   .** the aborted
1ef0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
1f00: 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 6f  is could lead to
1f10: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
1f20: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  tion..*/.#ifdef 
1f30: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
1f40: 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 4c  SIZE.# undef SQL
1f50: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a  ITE_MAX_PAGE_SIZ
1f60: 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  E.#endif.#define
1f70: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45   SQLITE_MAX_PAGE
1f80: 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f 2a  _SIZE 65536.../*
1f90: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
1fa0: 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 61  size of a databa
1fb0: 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 6e  se page..*/.#ifn
1fc0: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55  def SQLITE_DEFAU
1fd0: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64  LT_PAGE_SIZE.# d
1fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
1ff0: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 31  AULT_PAGE_SIZE 1
2000: 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 53  024.#endif.#if S
2010: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41  QLITE_DEFAULT_PA
2020: 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f 4d  GE_SIZE>SQLITE_M
2030: 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 75  AX_PAGE_SIZE.# u
2040: 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41  ndef SQLITE_DEFA
2050: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20  ULT_PAGE_SIZE.# 
2060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
2070: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20  FAULT_PAGE_SIZE 
2080: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
2090: 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  SIZE.#endif../*.
20a0: 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 69  ** Ordinarily, i
20b0: 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 78  f no value is ex
20c0: 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 65  plicitly provide
20d0: 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 65  d, SQLite create
20e0: 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 77  s databases.** w
20f0: 69 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 51  ith page size SQ
2100: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47  LITE_DEFAULT_PAG
2110: 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 2c  E_SIZE. However,
2120: 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 69   based on certai
2130: 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 72  n.** device char
2140: 61 63 74 65 72 69 73 74 69 63 73 20 28 73 65 63  acteristics (sec
2150: 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 6f  tor-size and ato
2160: 6d 69 63 20 77 72 69 74 65 28 29 20 73 75 70 70  mic write() supp
2170: 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  ort),.** SQLite 
2180: 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 72  may choose a lar
2190: 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 20  ger value. This 
21a0: 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 20  constant is the 
21b0: 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a 2a  maximum value.**
21c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 6f   SQLite will cho
21d0: 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e 0a  ose on its own..
21e0: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
21f0: 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41  E_MAX_DEFAULT_PA
2200: 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65  GE_SIZE.# define
2210: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41   SQLITE_MAX_DEFA
2220: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 31  ULT_PAGE_SIZE 81
2230: 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51  92.#endif.#if SQ
2240: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54  LITE_MAX_DEFAULT
2250: 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54  _PAGE_SIZE>SQLIT
2260: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a  E_MAX_PAGE_SIZE.
2270: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  # undef SQLITE_M
2280: 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f  AX_DEFAULT_PAGE_
2290: 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51  SIZE.# define SQ
22a0: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54  LITE_MAX_DEFAULT
22b0: 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 54  _PAGE_SIZE SQLIT
22c0: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a  E_MAX_PAGE_SIZE.
22d0: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 4d  #endif.../*.** M
22e0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
22f0: 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 61   pages in one da
2300: 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
2310: 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c 6c  ** This is reall
2320: 79 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 75  y just the defau
2330: 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
2340: 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20   max_page_count 
2350: 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 20  pragma..** This 
2360: 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f 77  value can be low
2370: 65 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 29  ered (or raised)
2380: 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
2390: 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 6d  ng that the.** m
23a0: 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d 61  ax_page_count ma
23b0: 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  cro..*/.#ifndef 
23c0: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
23d0: 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 53  COUNT.# define S
23e0: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43  QLITE_MAX_PAGE_C
23f0: 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 0a  OUNT 1073741823.
2400: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61  #endif../*.** Ma
2410: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 6e  ximum length (in
2420: 20 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 70   bytes) of the p
2430: 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b 45  attern in a LIKE
2440: 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 72   or GLOB.** oper
2450: 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  ator..*/.#ifndef
2460: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45   SQLITE_MAX_LIKE
2470: 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 0a  _PATTERN_LENGTH.
2480: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2490: 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MAX_LIKE_PATTERN
24a0: 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 65  _LENGTH 50000.#e
24b0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 69  ndif../*.** Maxi
24c0: 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
24d0: 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
24e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 6c  ers..**.** A val
24f0: 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 68  ue of 1 means th
2500: 61 74 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  at a trigger pro
2510: 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 65  gram will not be
2520: 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 0a   able to itself.
2530: 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 67  ** fire any trig
2540: 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f 66  gers. A value of
2550: 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f   0 means that no
2560: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
2570: 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 79  s at all .** may
2580: 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a 2f   be executed..*/
2590: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
25a0: 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MAX_TRIGGER_DEPT
25b0: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  H.# define SQLIT
25c0: 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45  E_MAX_TRIGGER_DE
25d0: 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a  PTH 1000.#endif.
25e0: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
25f0: 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c 69   End of sqliteLi
2600: 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  mit.h **********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
2630: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
2640: 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72   Continuing wher
2650: 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e  e we left off in
2660: 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a   sqliteInt.h ***
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
2680: 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 69  ../* Disable nui
2690: 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 6f  sance warnings o
26a0: 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 6c  n Borland compil
26b0: 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e  ers */.#if defin
26c0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
26d0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 72  .#pragma warn -r
26e0: 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 6c  ch /* unreachabl
26f0: 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 6d  e code */.#pragm
2700: 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 43  a warn -ccc /* C
2710: 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 61  ondition is alwa
2720: 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65  ys true or false
2730: 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 6e   */.#pragma warn
2740: 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e 65   -aus /* Assigne
2750: 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 72  d value is never
2760: 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d 61   used */.#pragma
2770: 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 6f   warn -csu /* Co
2780: 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 61  mparing signed a
2790: 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a 23  nd unsigned */.#
27a0: 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 61  pragma warn -spa
27b0: 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 70   /* Suspicious p
27c0: 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 69  ointer arithmeti
27d0: 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20  c */.#endif../* 
27e0: 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f  Needed for vario
27f0: 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e  us definitions..
2800: 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 4e  . */.#ifndef _GN
2810: 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 6e  U_SOURCE.# defin
2820: 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65  e _GNU_SOURCE.#e
2830: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c  ndif../*.** Incl
2840: 75 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61  ude standard hea
2850: 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63  der files as nec
2860: 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66  essary.*/.#ifdef
2870: 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23   HAVE_STDINT_H.#
2880: 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e  include <stdint.
2890: 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66  h>.#endif.#ifdef
28a0: 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48   HAVE_INTTYPES_H
28b0: 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79  .#include <intty
28c0: 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f  pes.h>.#endif../
28d0: 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
28e0: 6e 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  ng macros are us
28f0: 65 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74  ed to cast point
2900: 65 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20  ers to integers 
2910: 61 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  and.** integers 
2920: 74 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68  to pointers.  Th
2930: 65 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69  e way you do thi
2940: 73 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  s varies from on
2950: 65 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f  e compiler.** to
2960: 20 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65   the next, so we
2970: 20 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20   have developed 
2980: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65  the following se
2990: 74 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65  t of #if stateme
29a0: 6e 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61  nts.** to genera
29b0: 74 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d  te appropriate m
29c0: 61 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65  acros for a wide
29d0: 20 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c   range of compil
29e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ers..**.** The c
29f0: 6f 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 61  orrect "ANSI" wa
2a00: 79 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20  y to do this is 
2a10: 74 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 74  to use the intpt
2a20: 72 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e  r_t type. .** Un
2a30: 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61  fortunately, tha
2a40: 74 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74  t typedef is not
2a50: 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c   available on al
2a60: 6c 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a  l compilers, or.
2a70: 2a 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 69  ** if it is avai
2a80: 6c 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72  lable, it requir
2a90: 65 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f  es an #include o
2aa0: 66 20 73 70 65 63 69 66 69 63 20 68 65 61 64 65  f specific heade
2ab0: 72 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20  rs.** that vary 
2ac0: 66 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65  from one machine
2ad0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a   to the next..**
2ae0: 0a 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30  .** Ticket #3860
2af0: 3a 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d  :  The llvm-gcc-
2b00: 34 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f  4.2 compiler fro
2b10: 6d 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f  m Apple chokes o
2b20: 6e 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a  n.** the ((void*
2b30: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29  )&((char*)0)[X])
2b40: 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74   construct.  But
2b50: 20 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20   MSVC chokes on 
2b60: 28 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a  ((void*)(X))..**
2b70: 20 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64   So we have to d
2b80: 65 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73  efine the macros
2b90: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61   in different wa
2ba0: 79 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ys depending on 
2bb0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e  the.** compiler.
2bc0: 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28  .*/.#if defined(
2bd0: 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f  __PTRDIFF_TYPE__
2be0: 29 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20  )  /* This case 
2bf0: 73 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20  should work for 
2c00: 47 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20  GCC */.# define 
2c10: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54  SQLITE_INT_TO_PT
2c20: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f  R(X)  ((void*)(_
2c30: 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29  _PTRDIFF_TYPE__)
2c40: 28 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51  (X)).# define SQ
2c50: 4c 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28  LITE_PTR_TO_INT(
2c60: 58 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52  X)  ((int)(__PTR
2c70: 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29  DIFF_TYPE__)(X))
2c80: 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28  .#elif !defined(
2c90: 5f 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20  __GNUC__)       
2ca0: 2f 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d  /* Works for com
2cb0: 70 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61  pilers other tha
2cc0: 6e 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69  n LLVM */.# defi
2cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f  ne SQLITE_INT_TO
2ce0: 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a  _PTR(X)  ((void*
2cf0: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29  )&((char*)0)[X])
2d00: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2d10: 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20  _PTR_TO_INT(X)  
2d20: 28 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58  ((int)(((char*)X
2d30: 29 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c  )-(char*)0)).#el
2d40: 69 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f  if defined(HAVE_
2d50: 53 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55  STDINT_H)   /* U
2d60: 73 65 20 74 68 69 73 20 63 61 73 65 20 69 66 20  se this case if 
2d70: 77 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 61  we have ANSI hea
2d80: 64 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65  ders */.# define
2d90: 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50   SQLITE_INT_TO_P
2da0: 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28  TR(X)  ((void*)(
2db0: 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20  intptr_t)(X)).# 
2dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54  define SQLITE_PT
2dd0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69  R_TO_INT(X)  ((i
2de0: 6e 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29  nt)(intptr_t)(X)
2df0: 29 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 20  ).#else         
2e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e10: 20 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20   /* Generates a 
2e20: 77 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74  warning - but it
2e30: 20 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f   always works */
2e40: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2e50: 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20  _INT_TO_PTR(X)  
2e60: 28 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64  ((void*)(X)).# d
2e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52  efine SQLITE_PTR
2e80: 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e  _TO_INT(X)  ((in
2e90: 74 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f  t)(X)).#endif../
2ea0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
2eb0: 54 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f  THREADSAFE macro
2ec0: 20 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 64   must be defined
2ed0: 20 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a   as 0, 1, or 2..
2ee0: 2a 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78  ** 0 means mutex
2ef0: 65 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74  es are permanent
2f00: 6c 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74  ly disable and t
2f10: 68 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65  he library is ne
2f20: 76 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66  ver.** threadsaf
2f30: 65 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20  e.  1 means the 
2f40: 6c 69 62 72 61 72 79 20 69 73 20 73 65 72 69 61  library is seria
2f50: 6c 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 74  lized which is t
2f60: 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65  he highest.** le
2f70: 76 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66  vel of threadsaf
2f80: 65 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68  ety.  2 means th
2f90: 65 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c 74  e libary is mult
2fa0: 69 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74  ithreaded - mult
2fb0: 69 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20  iple.** threads 
2fc0: 63 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61  can use SQLite a
2fd0: 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
2fe0: 20 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20   threads try to 
2ff0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
3000: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3010: 69 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  ion at the same 
3020: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65  time..**.** Olde
3030: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
3040: 4c 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74  Lite used an opt
3050: 69 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45  ional THREADSAFE
3060: 20 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75   macro..** We su
3070: 70 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c  pport that for l
3080: 65 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64  egacy..*/.#if !d
3090: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48  efined(SQLITE_TH
30a0: 52 45 41 44 53 41 46 45 29 0a 23 69 66 20 64 65  READSAFE).#if de
30b0: 66 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45  fined(THREADSAFE
30c0: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  ).# define SQLIT
30d0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 54 48 52  E_THREADSAFE THR
30e0: 45 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23 20  EADSAFE.#else.# 
30f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 48  define SQLITE_TH
3100: 52 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49 4d  READSAFE 1 /* IM
3110: 50 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30 39  P: R-07272-22309
3120: 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69   */.#endif.#endi
3130: 66 0a 0a 2f 2a 0a 2a 2a 20 50 6f 77 65 72 73 61  f../*.** Powersa
3140: 66 65 20 6f 76 65 72 77 72 69 74 65 20 69 73 20  fe overwrite is 
3150: 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
3160: 42 75 74 20 63 61 6e 20 62 65 20 74 75 72 6e 65  But can be turne
3170: 64 20 6f 66 66 20 75 73 69 6e 67 0a 2a 2a 20 74  d off using.** t
3180: 68 65 20 2d 44 53 51 4c 49 54 45 5f 50 4f 57 45  he -DSQLITE_POWE
3190: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 3d  RSAFE_OVERWRITE=
31a0: 30 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 6f  0 command-line o
31b0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ption..*/.#ifnde
31c0: 66 20 53 51 4c 49 54 45 5f 50 4f 57 45 52 53 41  f SQLITE_POWERSA
31d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 0a 23 20 64  FE_OVERWRITE.# d
31e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 4f 57  efine SQLITE_POW
31f0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
3200: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a   1.#endif../*.**
3210: 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46 41   The SQLITE_DEFA
3220: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 20 6d 61  ULT_MEMSTATUS ma
3230: 63 72 6f 20 6d 75 73 74 20 62 65 20 64 65 66 69  cro must be defi
3240: 6e 65 64 20 61 73 20 65 69 74 68 65 72 20 30 20  ned as either 0 
3250: 6f 72 20 31 2e 0a 2a 2a 20 49 74 20 64 65 74 65  or 1..** It dete
3260: 72 6d 69 6e 65 73 20 77 68 65 74 68 65 72 20 6f  rmines whether o
3270: 72 20 6e 6f 74 20 74 68 65 20 66 65 61 74 75 72  r not the featur
3280: 65 73 20 72 65 6c 61 74 65 64 20 74 6f 20 0a 2a  es related to .*
3290: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
32a0: 4d 45 4d 53 54 41 54 55 53 20 61 72 65 20 61 76  MEMSTATUS are av
32b0: 61 69 6c 61 62 6c 65 20 62 79 20 64 65 66 61 75  ailable by defau
32c0: 6c 74 20 6f 72 20 6e 6f 74 2e 20 54 68 69 73 20  lt or not. This 
32d0: 76 61 6c 75 65 20 63 61 6e 0a 2a 2a 20 62 65 20  value can.** be 
32e0: 6f 76 65 72 72 69 64 64 65 6e 20 61 74 20 72 75  overridden at ru
32f0: 6e 74 69 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ntime using the 
3300: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
3310: 20 41 50 49 2e 0a 2a 2f 0a 23 69 66 20 21 64 65   API..*/.#if !de
3320: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 46  fined(SQLITE_DEF
3330: 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 29 0a  AULT_MEMSTATUS).
3340: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
3350: 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
3360: 53 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  S 1.#endif../*.*
3370: 2a 20 45 78 61 63 74 6c 79 20 6f 6e 65 20 6f 66  * Exactly one of
3380: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d   the following m
3390: 61 63 72 6f 73 20 6d 75 73 74 20 62 65 20 64 65  acros must be de
33a0: 66 69 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  fined in order t
33b0: 6f 0a 2a 2a 20 73 70 65 63 69 66 79 20 77 68 69  o.** specify whi
33c0: 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ch memory alloca
33d0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 74  tion subsystem t
33e0: 6f 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 20 20 20  o use..**.**    
33f0: 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d   SQLITE_SYSTEM_M
3400: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 20 2f  ALLOC          /
3410: 2f 20 55 73 65 20 6e 6f 72 6d 61 6c 20 73 79 73  / Use normal sys
3420: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 20  tem malloc().** 
3430: 20 20 20 20 53 51 4c 49 54 45 5f 57 49 4e 33 32      SQLITE_WIN32
3440: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20  _MALLOC         
3450: 20 20 2f 2f 20 55 73 65 20 57 69 6e 33 32 20 6e    // Use Win32 n
3460: 61 74 69 76 65 20 68 65 61 70 20 41 50 49 0a 2a  ative heap API.*
3470: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 5a 45 52  *     SQLITE_ZER
3480: 4f 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  O_MALLOC        
3490: 20 20 20 20 2f 2f 20 55 73 65 20 61 20 73 74 75      // Use a stu
34a0: 62 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  b allocator that
34b0: 20 61 6c 77 61 79 73 20 66 61 69 6c 73 0a 2a 2a   always fails.**
34c0: 20 20 20 20 20 53 51 4c 49 54 45 5f 4d 45 4d 44       SQLITE_MEMD
34d0: 45 42 55 47 20 20 20 20 20 20 20 20 20 20 20 20  EBUG            
34e0: 20 20 20 2f 2f 20 44 65 62 75 67 67 69 6e 67 20     // Debugging 
34f0: 76 65 72 73 69 6f 6e 20 6f 66 20 73 79 73 74 65  version of syste
3500: 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a 2a 2a  m malloc().**.**
3510: 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69 66 20   On Windows, if 
3520: 74 68 65 20 53 51 4c 49 54 45 5f 57 49 4e 33 32  the SQLITE_WIN32
3530: 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41 54 45  _MALLOC_VALIDATE
3540: 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e 65   macro is define
3550: 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61 73 73  d and the.** ass
3560: 65 72 74 28 29 20 6d 61 63 72 6f 20 69 73 20 65  ert() macro is e
3570: 6e 61 62 6c 65 64 2c 20 65 61 63 68 20 63 61 6c  nabled, each cal
3580: 6c 20 69 6e 74 6f 20 74 68 65 20 57 69 6e 33 32  l into the Win32
3590: 20 6e 61 74 69 76 65 20 68 65 61 70 20 73 75 62   native heap sub
35a0: 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c 20 63  system.** will c
35b0: 61 75 73 65 20 48 65 61 70 56 61 6c 69 64 61 74  ause HeapValidat
35c0: 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e 20  e to be called. 
35d0: 20 49 66 20 68 65 61 70 20 76 61 6c 69 64 61 74   If heap validat
35e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69 6c 2c  ion should fail,
35f0: 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e   an.** assertion
3600: 20 77 69 6c 6c 20 62 65 20 74 72 69 67 67 65 72   will be trigger
3610: 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74 6f  ed..**.** (Histo
3620: 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54 68 65  rical note:  The
3630: 72 65 20 75 73 65 64 20 74 6f 20 62 65 20 73 65  re used to be se
3640: 76 65 72 61 6c 20 6f 74 68 65 72 20 6f 70 74 69  veral other opti
3650: 6f 6e 73 2c 20 62 75 74 20 77 65 27 76 65 0a 2a  ons, but we've.*
3660: 2a 20 70 61 72 65 64 20 69 74 20 64 6f 77 6e 20  * pared it down 
3670: 74 6f 20 6a 75 73 74 20 74 68 65 73 65 20 74 68  to just these th
3680: 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66 20 6e  ree.).**.** If n
3690: 6f 6e 65 20 6f 66 20 74 68 65 20 61 62 6f 76 65  one of the above
36a0: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
36b0: 65 6e 20 73 65 74 20 53 51 4c 49 54 45 5f 53 59  en set SQLITE_SY
36c0: 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73 0a 2a  STEM_MALLOC as.*
36d0: 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 0a 2a  * the default..*
36e0: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 51  /.#if defined(SQ
36f0: 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c  LITE_SYSTEM_MALL
3700: 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66 69 6e 65  OC) \.  + define
3710: 64 28 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d  d(SQLITE_WIN32_M
3720: 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66  ALLOC) \.  + def
3730: 69 6e 65 64 28 53 51 4c 49 54 45 5f 5a 45 52 4f  ined(SQLITE_ZERO
3740: 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64  _MALLOC) \.  + d
3750: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45  efined(SQLITE_ME
3760: 4d 44 45 42 55 47 29 3e 31 0a 23 20 65 72 72 6f  MDEBUG)>1.# erro
3770: 72 20 22 54 77 6f 20 6f 72 20 6d 6f 72 65 20 6f  r "Two or more o
3780: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
3790: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e  compile-time con
37a0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
37b0: 6e 73 5c 0a 20 61 72 65 20 64 65 66 69 6e 65 64  ns\. are defined
37c0: 20 62 75 74 20 61 74 20 6d 6f 73 74 20 6f 6e 65   but at most one
37d0: 20 69 73 20 61 6c 6c 6f 77 65 64 3a 5c 0a 20 53   is allowed:\. S
37e0: 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c  QLITE_SYSTEM_MAL
37f0: 4c 4f 43 2c 20 53 51 4c 49 54 45 5f 57 49 4e 33  LOC, SQLITE_WIN3
3800: 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 45  2_MALLOC, SQLITE
3810: 5f 4d 45 4d 44 45 42 55 47 2c 5c 0a 20 53 51 4c  _MEMDEBUG,\. SQL
3820: 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 22  ITE_ZERO_MALLOC"
3830: 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69  .#endif.#if defi
3840: 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45  ned(SQLITE_SYSTE
3850: 4d 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20  M_MALLOC) \.  + 
3860: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 57  defined(SQLITE_W
3870: 49 4e 33 32 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20  IN32_MALLOC) \. 
3880: 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54   + defined(SQLIT
3890: 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 29 20 5c  E_ZERO_MALLOC) \
38a0: 0a 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c  .  + defined(SQL
38b0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d 3d 30  ITE_MEMDEBUG)==0
38c0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
38d0: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 31  _SYSTEM_MALLOC 1
38e0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49  .#endif../*.** I
38f0: 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f  f SQLITE_MALLOC_
3900: 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20 6e 6f  SOFT_LIMIT is no
3910: 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 79  t zero, then try
3920: 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a 2a 20   to keep the.** 
3930: 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  sizes of memory 
3940: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65 6c 6f  allocations belo
3950: 77 20 74 68 69 73 20 76 61 6c 75 65 20 77 68 65  w this value whe
3960: 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2f 0a  re possible..*/.
3970: 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c  #if !defined(SQL
3980: 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f  ITE_MALLOC_SOFT_
3990: 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e 65 20  LIMIT).# define 
39a0: 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f  SQLITE_MALLOC_SO
39b0: 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a 23 65  FT_LIMIT 1024.#e
39c0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65 20 6e  ndif../*.** We n
39d0: 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20 5f 58  eed to define _X
39e0: 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73 20 66  OPEN_SOURCE as f
39f0: 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65 72 20  ollows in order 
3a00: 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72 65 63  to enable.** rec
3a10: 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 20 6f  ursive mutexes o
3a20: 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79 73 74  n most Unix syst
3a30: 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20 4f 53  ems.  But Mac OS
3a40: 20 58 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e   X is different.
3a50: 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e 5f 53  .** The _XOPEN_S
3a60: 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63 61 75  OURCE define cau
3a70: 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f 72  ses problems for
3a80: 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61 72 65   Mac OS X we are
3a90: 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69 74 20   told,.** so it 
3aa0: 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 72 65  is omitted there
3ab0: 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
3ac0: 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74 65 72  673..**.** Later
3ad0: 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74 20 5f   we learn that _
3ae0: 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69 73 20  XOPEN_SOURCE is 
3af0: 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f 72 72  poorly or incorr
3b00: 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ectly.** impleme
3b10: 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73 79 73  nted on some sys
3b20: 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61 76 6f  tems.  So we avo
3b30: 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74 20 61  id defining it a
3b40: 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74 20 69  t all.** if it i
3b50: 73 20 61 6c 72 65 61 64 79 20 64 65 66 69 6e 65  s already define
3b60: 64 20 6f 72 20 69 66 20 69 74 20 69 73 20 75 6e  d or if it is un
3b70: 6e 65 65 64 65 64 20 62 65 63 61 75 73 65 20 77  needed because w
3b80: 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64 6f 69  e are.** not doi
3b90: 6e 67 20 61 20 74 68 72 65 61 64 73 61 66 65 20  ng a threadsafe 
3ba0: 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74 20 23  build.  Ticket #
3bb0: 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2681..**.** See 
3bc0: 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32 37 34  also ticket #274
3bd0: 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e  1..*/.#if !defin
3be0: 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45  ed(_XOPEN_SOURCE
3bf0: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 5f  ) && !defined(__
3c00: 44 41 52 57 49 4e 5f 5f 29 20 26 26 20 21 64 65  DARWIN__) && !de
3c10: 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45 5f 5f 29  fined(__APPLE__)
3c20: 20 26 26 20 53 51 4c 49 54 45 5f 54 48 52 45 41   && SQLITE_THREA
3c30: 44 53 41 46 45 0a 23 20 20 64 65 66 69 6e 65 20  DSAFE.#  define 
3c40: 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 35 30  _XOPEN_SOURCE 50
3c50: 30 20 20 2f 2a 20 4e 65 65 64 65 64 20 74 6f 20  0  /* Needed to 
3c60: 65 6e 61 62 6c 65 20 70 74 68 72 65 61 64 20 72  enable pthread r
3c70: 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73  ecursive mutexes
3c80: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a   */.#endif../*.*
3c90: 2a 20 54 68 65 20 54 43 4c 20 68 65 61 64 65 72  * The TCL header
3ca0: 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65 65 64 65  s are only neede
3cb0: 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67  d when compiling
3cc0: 20 74 68 65 20 54 43 4c 20 62 69 6e 64 69 6e 67   the TCL binding
3cd0: 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  s..*/.#if define
3ce0: 64 28 53 51 4c 49 54 45 5f 54 43 4c 29 20 7c 7c  d(SQLITE_TCL) ||
3cf0: 20 64 65 66 69 6e 65 64 28 54 43 4c 53 48 29 0a   defined(TCLSH).
3d00: 23 20 69 6e 63 6c 75 64 65 20 3c 74 63 6c 2e 68  # include <tcl.h
3d10: 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  >.#endif../*.** 
3d20: 4e 44 45 42 55 47 20 61 6e 64 20 53 51 4c 49 54  NDEBUG and SQLIT
3d30: 45 5f 44 45 42 55 47 20 61 72 65 20 6f 70 70 6f  E_DEBUG are oppo
3d40: 73 69 74 65 73 2e 20 20 49 74 20 73 68 6f 75 6c  sites.  It shoul
3d50: 64 20 61 6c 77 61 79 73 20 62 65 20 74 72 75 65  d always be true
3d60: 20 74 68 61 74 0a 2a 2a 20 64 65 66 69 6e 65 64   that.** defined
3d70: 28 4e 44 45 42 55 47 29 3d 3d 21 64 65 66 69 6e  (NDEBUG)==!defin
3d80: 65 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29  ed(SQLITE_DEBUG)
3d90: 2e 20 20 49 66 20 74 68 69 73 20 69 73 20 6e 6f  .  If this is no
3da0: 74 20 63 75 72 72 65 6e 74 6c 79 20 74 72 75 65  t currently true
3db0: 2c 0a 2a 2a 20 6d 61 6b 65 20 69 74 20 74 72 75  ,.** make it tru
3dc0: 65 20 62 79 20 64 65 66 69 6e 69 6e 67 20 6f 72  e by defining or
3dd0: 20 75 6e 64 65 66 69 6e 69 6e 67 20 4e 44 45 42   undefining NDEB
3de0: 55 47 2e 0a 2a 2a 0a 2a 2a 20 53 65 74 74 69 6e  UG..**.** Settin
3df0: 67 20 4e 44 45 42 55 47 20 6d 61 6b 65 73 20 74  g NDEBUG makes t
3e00: 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c 65 72 20  he code smaller 
3e10: 61 6e 64 20 72 75 6e 20 66 61 73 74 65 72 20 62  and run faster b
3e20: 79 20 64 69 73 61 62 6c 69 6e 67 20 74 68 65 0a  y disabling the.
3e30: 2a 2a 20 6e 75 6d 62 65 72 20 61 73 73 65 72 74  ** number assert
3e40: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
3e50: 20 74 68 65 20 63 6f 64 65 2e 20 20 53 6f 20 77   the code.  So w
3e60: 65 20 77 61 6e 74 20 74 68 65 20 64 65 66 61 75  e want the defau
3e70: 6c 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20  lt action.** to 
3e80: 62 65 20 66 6f 72 20 4e 44 45 42 55 47 20 74 6f  be for NDEBUG to
3e90: 20 62 65 20 73 65 74 20 61 6e 64 20 4e 44 45 42   be set and NDEB
3ea0: 55 47 20 74 6f 20 62 65 20 75 6e 64 65 66 69 6e  UG to be undefin
3eb0: 65 64 20 6f 6e 6c 79 20 69 66 20 53 51 4c 49 54  ed only if SQLIT
3ec0: 45 5f 44 45 42 55 47 0a 2a 2a 20 69 73 20 73 65  E_DEBUG.** is se
3ed0: 74 2e 20 20 54 68 75 73 20 4e 44 45 42 55 47 20  t.  Thus NDEBUG 
3ee0: 62 65 63 6f 6d 65 73 20 61 6e 20 6f 70 74 2d 69  becomes an opt-i
3ef0: 6e 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 6e  n rather than an
3f00: 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66 65 61 74   opt-out.** feat
3f10: 75 72 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66  ure..*/.#if !def
3f20: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 26 26 20  ined(NDEBUG) && 
3f30: 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f  !defined(SQLITE_
3f40: 44 45 42 55 47 29 20 0a 23 20 64 65 66 69 6e 65  DEBUG) .# define
3f50: 20 4e 44 45 42 55 47 20 31 0a 23 65 6e 64 69 66   NDEBUG 1.#endif
3f60: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 4e 44 45  .#if defined(NDE
3f70: 42 55 47 29 20 26 26 20 64 65 66 69 6e 65 64 28  BUG) && defined(
3f80: 53 51 4c 49 54 45 5f 44 45 42 55 47 29 0a 23 20  SQLITE_DEBUG).# 
3f90: 75 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 65 6e  undef NDEBUG.#en
3fa0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  dif../*.** The t
3fb0: 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20  estcase() macro 
3fc0: 69 73 20 75 73 65 64 20 74 6f 20 61 69 64 20 69  is used to aid i
3fd0: 6e 20 63 6f 76 65 72 61 67 65 20 74 65 73 74 69  n coverage testi
3fe0: 6e 67 2e 20 20 57 68 65 6e 20 0a 2a 2a 20 64 6f  ng.  When .** do
3ff0: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73  ing coverage tes
4000: 74 69 6e 67 2c 20 74 68 65 20 63 6f 6e 64 69 74  ting, the condit
4010: 69 6f 6e 20 69 6e 73 69 64 65 20 74 68 65 20 61  ion inside the a
4020: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 65  rgument to.** te
4030: 73 74 63 61 73 65 28 29 20 6d 75 73 74 20 62 65  stcase() must be
4040: 20 65 76 61 6c 75 61 74 65 64 20 62 6f 74 68 20   evaluated both 
4050: 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 20 69  true and false i
4060: 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 67 65  n order to.** ge
4070: 74 20 66 75 6c 6c 20 62 72 61 6e 63 68 20 63 6f  t full branch co
4080: 76 65 72 61 67 65 2e 20 20 54 68 65 20 74 65 73  verage.  The tes
4090: 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20 69 73  tcase() macro is
40a0: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 74 6f 20   inserted.** to 
40b0: 68 65 6c 70 20 65 6e 73 75 72 65 20 61 64 65 71  help ensure adeq
40c0: 75 61 74 65 20 74 65 73 74 20 63 6f 76 65 72 61  uate test covera
40d0: 67 65 20 69 6e 20 70 6c 61 63 65 73 20 77 68 65  ge in places whe
40e0: 72 65 20 73 69 6d 70 6c 65 0a 2a 2a 20 63 6f 6e  re simple.** con
40f0: 64 69 74 69 6f 6e 2f 64 65 63 69 73 69 6f 6e 20  dition/decision 
4100: 63 6f 76 65 72 61 67 65 20 69 73 20 69 6e 61 64  coverage is inad
4110: 65 71 75 61 74 65 2e 20 20 46 6f 72 20 65 78 61  equate.  For exa
4120: 6d 70 6c 65 2c 20 74 65 73 74 63 61 73 65 28 29  mple, testcase()
4130: 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
4140: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 62 6f 75  to make sure bou
4150: 6e 64 61 72 79 20 76 61 6c 75 65 73 20 61 72 65  ndary values are
4160: 20 74 65 73 74 65 64 2e 20 20 46 6f 72 0a 2a 2a   tested.  For.**
4170: 20 62 69 74 6d 61 73 6b 20 74 65 73 74 73 2c 20   bitmask tests, 
4180: 74 65 73 74 63 61 73 65 28 29 20 63 61 6e 20 62  testcase() can b
4190: 65 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73  e used to make s
41a0: 75 72 65 20 65 61 63 68 20 62 69 74 0a 2a 2a 20  ure each bit.** 
41b0: 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 61  is significant a
41c0: 6e 64 20 75 73 65 64 20 61 74 20 6c 65 61 73 74  nd used at least
41d0: 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 77 69 74 63   once.  On switc
41e0: 68 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  h statements.** 
41f0: 77 68 65 72 65 20 6d 75 6c 74 69 70 6c 65 20 63  where multiple c
4200: 61 73 65 73 20 67 6f 20 74 6f 20 74 68 65 20 73  ases go to the s
4210: 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20 63 6f 64  ame block of cod
4220: 65 2c 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a  e, testcase().**
4230: 20 63 61 6e 20 69 6e 73 75 72 65 20 74 68 61 74   can insure that
4240: 20 61 6c 6c 20 63 61 73 65 73 20 61 72 65 20 65   all cases are e
4250: 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2f 0a  valuated..**.*/.
4260: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 43 4f  #ifdef SQLITE_CO
4270: 56 45 52 41 47 45 5f 54 45 53 54 0a 53 51 4c 49  VERAGE_TEST.SQLI
4280: 54 45 5f 50 52 49 56 41 54 45 20 20 20 76 6f 69  TE_PRIVATE   voi
4290: 64 20 73 71 6c 69 74 65 33 43 6f 76 65 72 61 67  d sqlite3Coverag
42a0: 65 28 69 6e 74 29 3b 0a 23 20 64 65 66 69 6e 65  e(int);.# define
42b0: 20 74 65 73 74 63 61 73 65 28 58 29 20 20 69 66   testcase(X)  if
42c0: 28 20 58 20 29 7b 20 73 71 6c 69 74 65 33 43 6f  ( X ){ sqlite3Co
42d0: 76 65 72 61 67 65 28 5f 5f 4c 49 4e 45 5f 5f 29  verage(__LINE__)
42e0: 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  ; }.#else.# defi
42f0: 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 0a 23  ne testcase(X).#
4300: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
4310: 20 54 45 53 54 4f 4e 4c 59 20 6d 61 63 72 6f 20   TESTONLY macro 
4320: 69 73 20 75 73 65 64 20 74 6f 20 65 6e 63 6c 6f  is used to enclo
4330: 73 65 20 76 61 72 69 61 62 6c 65 20 64 65 63 6c  se variable decl
4340: 61 72 61 74 69 6f 6e 73 20 6f 72 0a 2a 2a 20 6f  arations or.** o
4350: 74 68 65 72 20 62 69 74 73 20 6f 66 20 63 6f 64  ther bits of cod
4360: 65 20 74 68 61 74 20 61 72 65 20 6e 65 65 64 65  e that are neede
4370: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 74 68 65  d to support the
4380: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 77 69   arguments.** wi
4390: 74 68 69 6e 20 74 65 73 74 63 61 73 65 28 29 20  thin testcase() 
43a0: 61 6e 64 20 61 73 73 65 72 74 28 29 20 6d 61 63  and assert() mac
43b0: 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66  ros..*/.#if !def
43c0: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 7c 7c 20  ined(NDEBUG) || 
43d0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 43  defined(SQLITE_C
43e0: 4f 56 45 52 41 47 45 5f 54 45 53 54 29 0a 23 20  OVERAGE_TEST).# 
43f0: 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28  define TESTONLY(
4400: 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65  X)  X.#else.# de
4410: 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28 58 29  fine TESTONLY(X)
4420: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 53  .#endif../*.** S
4430: 6f 6d 65 74 69 6d 65 73 20 77 65 20 6e 65 65 64  ometimes we need
4440: 20 61 20 73 6d 61 6c 6c 20 61 6d 6f 75 6e 74 20   a small amount 
4450: 6f 66 20 63 6f 64 65 20 73 75 63 68 20 61 73 20  of code such as 
4460: 61 20 76 61 72 69 61 62 6c 65 20 69 6e 69 74 69  a variable initi
4470: 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  alization.** to 
4480: 73 65 74 75 70 20 66 6f 72 20 61 20 6c 61 74 65  setup for a late
4490: 72 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  r assert() state
44a0: 6d 65 6e 74 2e 20 20 57 65 20 64 6f 20 6e 6f 74  ment.  We do not
44b0: 20 77 61 6e 74 20 74 68 69 73 20 63 6f 64 65 20   want this code 
44c0: 74 6f 0a 2a 2a 20 61 70 70 65 61 72 20 77 68 65  to.** appear whe
44d0: 6e 20 61 73 73 65 72 74 28 29 20 69 73 20 64 69  n assert() is di
44e0: 73 61 62 6c 65 64 2e 20 20 54 68 65 20 66 6f 6c  sabled.  The fol
44f0: 6c 6f 77 69 6e 67 20 6d 61 63 72 6f 20 69 73 20  lowing macro is 
4500: 74 68 65 72 65 66 6f 72 65 0a 2a 2a 20 75 73 65  therefore.** use
4510: 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 61  d to contain tha
4520: 74 20 73 65 74 75 70 20 63 6f 64 65 2e 20 20 54  t setup code.  T
4530: 68 65 20 22 56 56 41 22 20 61 63 72 6f 6e 79 6d  he "VVA" acronym
4540: 20 73 74 61 6e 64 73 20 66 6f 72 0a 2a 2a 20 22   stands for.** "
4550: 56 65 72 69 66 69 63 61 74 69 6f 6e 2c 20 56 61  Verification, Va
4560: 6c 69 64 61 74 69 6f 6e 2c 20 61 6e 64 20 41 63  lidation, and Ac
4570: 63 72 65 64 69 74 61 74 69 6f 6e 22 2e 20 20 49  creditation".  I
4580: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
4590: 68 65 0a 2a 2a 20 63 6f 64 65 20 77 69 74 68 69  he.** code withi
45a0: 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 20 77 69 6c  n VVA_ONLY() wil
45b0: 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 75 72 69 6e  l only run durin
45c0: 67 20 76 65 72 69 66 69 63 61 74 69 6f 6e 20 70  g verification p
45d0: 72 6f 63 65 73 73 65 73 2e 0a 2a 2f 0a 23 69 66  rocesses..*/.#if
45e0: 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 20 64 65  ndef NDEBUG.# de
45f0: 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29  fine VVA_ONLY(X)
4600: 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65 66 69    X.#else.# defi
4610: 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29 0a 23  ne VVA_ONLY(X).#
4620: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
4630: 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45   ALWAYS and NEVE
4640: 52 20 6d 61 63 72 6f 73 20 73 75 72 72 6f 75 6e  R macros surroun
4650: 64 20 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73  d boolean expres
4660: 73 69 6f 6e 73 20 77 68 69 63 68 20 0a 2a 2a 20  sions which .** 
4670: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
4680: 61 6c 77 61 79 73 20 62 65 20 74 72 75 65 20 6f  always be true o
4690: 72 20 66 61 6c 73 65 2c 20 72 65 73 70 65 63 74  r false, respect
46a0: 69 76 65 6c 79 2e 20 20 53 75 63 68 0a 2a 2a 20  ively.  Such.** 
46b0: 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 75 6c  expressions coul
46c0: 64 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f  d be omitted fro
46d0: 6d 20 74 68 65 20 63 6f 64 65 20 63 6f 6d 70 6c  m the code compl
46e0: 65 74 65 6c 79 2e 20 20 42 75 74 20 74 68 65 79  etely.  But they
46f0: 0a 2a 2a 20 61 72 65 20 69 6e 63 6c 75 64 65 64  .** are included
4700: 20 69 6e 20 61 20 66 65 77 20 63 61 73 65 73 20   in a few cases 
4710: 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 68 61  in order to enha
4720: 6e 63 65 20 74 68 65 20 72 65 73 69 6c 69 65 6e  nce the resilien
4730: 63 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  ce.** of SQLite 
4740: 74 6f 20 75 6e 65 78 70 65 63 74 65 64 20 62 65  to unexpected be
4750: 68 61 76 69 6f 72 20 2d 20 74 6f 20 6d 61 6b 65  havior - to make
4760: 20 74 68 65 20 63 6f 64 65 20 22 73 65 6c 66 2d   the code "self-
4770: 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 6f 72 20 22  healing".** or "
4780: 64 75 63 74 69 6c 65 22 20 72 61 74 68 65 72 20  ductile" rather 
4790: 74 68 61 6e 20 62 65 69 6e 67 20 22 62 72 69 74  than being "brit
47a0: 74 6c 65 22 20 61 6e 64 20 63 72 61 73 68 69 6e  tle" and crashin
47b0: 67 20 61 74 20 74 68 65 20 66 69 72 73 74 0a 2a  g at the first.*
47c0: 2a 20 68 69 6e 74 20 6f 66 20 75 6e 70 6c 61 6e  * hint of unplan
47d0: 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
47e0: 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
47f0: 64 73 2c 20 41 4c 57 41 59 53 20 61 6e 64 20 4e  ds, ALWAYS and N
4800: 45 56 45 52 20 61 72 65 20 61 64 64 65 64 20 66  EVER are added f
4810: 6f 72 20 64 65 66 65 6e 73 69 76 65 20 63 6f 64  or defensive cod
4820: 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 64 6f  e..**.** When do
4830: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73  ing coverage tes
4840: 74 69 6e 67 20 41 4c 57 41 59 53 20 61 6e 64 20  ting ALWAYS and 
4850: 4e 45 56 45 52 20 61 72 65 20 68 61 72 64 2d 63  NEVER are hard-c
4860: 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 65 20 74 72  oded to.** be tr
4870: 75 65 20 61 6e 64 20 66 61 6c 73 65 20 73 6f 20  ue and false so 
4880: 74 68 61 74 20 74 68 65 20 75 6e 72 65 61 63 68  that the unreach
4890: 61 62 6c 65 20 63 6f 64 65 20 74 68 65 6e 20 73  able code then s
48a0: 70 65 63 69 66 79 20 77 69 6c 6c 0a 2a 2a 20 6e  pecify will.** n
48b0: 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 61 73  ot be counted as
48c0: 20 75 6e 74 65 73 74 65 64 20 63 6f 64 65 2e 0a   untested code..
48d0: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53  */.#if defined(S
48e0: 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54  QLITE_COVERAGE_T
48f0: 45 53 54 29 0a 23 20 64 65 66 69 6e 65 20 41 4c  EST).# define AL
4900: 57 41 59 53 28 58 29 20 20 20 20 20 20 28 31 29  WAYS(X)      (1)
4910: 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 28  .# define NEVER(
4920: 58 29 20 20 20 20 20 20 20 28 30 29 0a 23 65 6c  X)       (0).#el
4930: 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42  if !defined(NDEB
4940: 55 47 29 0a 23 20 64 65 66 69 6e 65 20 41 4c 57  UG).# define ALW
4950: 41 59 53 28 58 29 20 20 20 20 20 20 28 28 58 29  AYS(X)      ((X)
4960: 3f 31 3a 28 61 73 73 65 72 74 28 30 29 2c 30 29  ?1:(assert(0),0)
4970: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52  ).# define NEVER
4980: 28 58 29 20 20 20 20 20 20 20 28 28 58 29 3f 28  (X)       ((X)?(
4990: 61 73 73 65 72 74 28 30 29 2c 31 29 3a 30 29 0a  assert(0),1):0).
49a0: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 41  #else.# define A
49b0: 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28 58  LWAYS(X)      (X
49c0: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52  ).# define NEVER
49d0: 28 58 29 20 20 20 20 20 20 20 28 58 29 0a 23 65  (X)       (X).#e
49e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75  ndif../*.** Retu
49f0: 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  rn true (non-zer
4a00: 6f 29 20 69 66 20 74 68 65 20 69 6e 70 75 74 20  o) if the input 
4a10: 69 73 20 61 20 69 6e 74 65 67 65 72 20 74 68 61  is a integer tha
4a20: 74 20 69 73 20 74 6f 6f 20 6c 61 72 67 65 0a 2a  t is too large.*
4a30: 2a 20 74 6f 20 66 69 74 20 69 6e 20 33 32 2d 62  * to fit in 32-b
4a40: 69 74 73 2e 20 20 54 68 69 73 20 6d 61 63 72 6f  its.  This macro
4a50: 20 69 73 20 75 73 65 64 20 69 6e 73 69 64 65 20   is used inside 
4a60: 6f 66 20 76 61 72 69 6f 75 73 20 74 65 73 74 63  of various testc
4a70: 61 73 65 28 29 0a 2a 2a 20 6d 61 63 72 6f 73 20  ase().** macros 
4a80: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 77  to verify that w
4a90: 65 20 68 61 76 65 20 74 65 73 74 65 64 20 53 51  e have tested SQ
4aa0: 4c 69 74 65 20 66 6f 72 20 6c 61 72 67 65 2d 66  Lite for large-f
4ab0: 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a  ile support..*/.
4ac0: 23 64 65 66 69 6e 65 20 49 53 5f 42 49 47 5f 49  #define IS_BIG_I
4ad0: 4e 54 28 58 29 20 20 28 28 28 58 29 26 7e 28 69  NT(X)  (((X)&~(i
4ae0: 36 34 29 30 78 66 66 66 66 66 66 66 66 29 21 3d  64)0xffffffff)!=
4af0: 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61  0)../*.** The ma
4b00: 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 28 29 20 69  cro unlikely() i
4b10: 73 20 61 20 68 69 6e 74 20 74 68 61 74 20 73 75  s a hint that su
4b20: 72 72 6f 75 6e 64 73 20 61 20 62 6f 6f 6c 65 61  rrounds a boolea
4b30: 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
4b40: 74 68 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20  that is usually 
4b50: 66 61 6c 73 65 2e 20 20 4d 61 63 72 6f 20 6c 69  false.  Macro li
4b60: 6b 65 6c 79 28 29 20 73 75 72 72 6f 75 6e 64 73  kely() surrounds
4b70: 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 65 78  .** a boolean ex
4b80: 70 72 65 73 73 69 6f 6e 20 74 68 61 74 20 69 73  pression that is
4b90: 20 75 73 75 61 6c 6c 79 20 74 72 75 65 2e 20 20   usually true.  
4ba0: 47 43 43 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  GCC is able to.*
4bb0: 2a 20 75 73 65 20 74 68 65 73 65 20 68 69 6e 74  * use these hint
4bc0: 73 20 74 6f 20 67 65 6e 65 72 61 74 65 20 62 65  s to generate be
4bd0: 74 74 65 72 20 63 6f 64 65 2c 20 73 6f 6d 65 74  tter code, somet
4be0: 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66  imes..*/.#if def
4bf0: 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26  ined(__GNUC__) &
4c00: 26 20 30 0a 23 20 64 65 66 69 6e 65 20 6c 69 6b  & 0.# define lik
4c10: 65 6c 79 28 58 29 20 20 20 20 5f 5f 62 75 69 6c  ely(X)    __buil
4c20: 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 31  tin_expect((X),1
4c30: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b  ).# define unlik
4c40: 65 6c 79 28 58 29 20 20 5f 5f 62 75 69 6c 74 69  ely(X)  __builti
4c50: 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 30 29 0a  n_expect((X),0).
4c60: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 6c  #else.# define l
4c70: 69 6b 65 6c 79 28 58 29 20 20 20 20 21 21 28 58  ikely(X)    !!(X
4c80: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b  ).# define unlik
4c90: 65 6c 79 28 58 29 20 20 21 21 28 58 29 0a 23 65  ely(X)  !!(X).#e
4ca0: 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  ndif../*********
4cb0: 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71  ***** Include sq
4cc0: 6c 69 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d  lite3.h in the m
4cd0: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49  iddle of sqliteI
4ce0: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
4cf0: 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****/./*********
4d00: 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65  ***** Begin file
4d10: 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a   sqlite3.h *****
4d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d40: 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31  ****/./*.** 2001
4d50: 20 53 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a   September 15.**
4d60: 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64  .** The author d
4d70: 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67  isclaims copyrig
4d80: 68 74 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63  ht to this sourc
4d90: 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63  e code.  In plac
4da0: 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20  e of.** a legal 
4db0: 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 69 73 20  notice, here is 
4dc0: 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a  a blessing:.**.*
4dd0: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20  *    May you do 
4de0: 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69  good and not evi
4df0: 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  l..**    May you
4e00: 20 66 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73   find forgivenes
4e10: 73 20 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61  s for yourself a
4e20: 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72  nd forgive other
4e30: 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  s..**    May you
4e40: 20 73 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e   share freely, n
4e50: 65 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65  ever taking more
4e60: 20 74 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a   than you give..
4e70: 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **.*************
4e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ea0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4eb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20  ************.** 
4ec0: 54 68 69 73 20 68 65 61 64 65 72 20 66 69 6c 65  This header file
4ed0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
4ee0: 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20  erface that the 
4ef0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a  SQLite library.*
4f00: 2a 20 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c  * presents to cl
4f10: 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20  ient programs.  
4f20: 49 66 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c  If a C-function,
4f30: 20 73 74 72 75 63 74 75 72 65 2c 20 64 61 74 61   structure, data
4f40: 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73  type,.** or cons
4f50: 74 61 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20  tant definition 
4f60: 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
4f70: 69 6e 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68  in this file, th
4f80: 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  en it is.** not 
4f90: 61 20 70 75 62 6c 69 73 68 65 64 20 41 50 49 20  a published API 
4fa0: 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75  of SQLite, is su
4fb0: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
4fc0: 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63  without.** notic
4fd0: 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  e, and should no
4fe0: 74 20 62 65 20 72 65 66 65 72 65 6e 63 65 64 20  t be referenced 
4ff0: 62 79 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74  by programs that
5000: 20 75 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a   use SQLite..**.
5010: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64  ** Some of the d
5020: 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20  efinitions that 
5030: 61 72 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65  are in this file
5040: 20 61 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a   are marked as.*
5050: 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22  * "experimental"
5060: 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20  .  Experimental 
5070: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
5080: 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66  ormally new.** f
5090: 65 61 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79  eatures recently
50a0: 20 61 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65   added to SQLite
50b0: 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74  .  We do not ant
50c0: 69 63 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a  icipate changes.
50d0: 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74  ** to experiment
50e0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 62 75  al interfaces bu
50f0: 74 20 72 65 73 65 72 76 65 20 74 68 65 20 72 69  t reserve the ri
5100: 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  ght to make mino
5110: 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20  r changes.** if 
5120: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
5130: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
5140: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
5150: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
5160: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
5170: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
5180: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
5190: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
51a0: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
51b0: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
51c0: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
51d0: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
51e0: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
51f0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
5200: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
5210: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
5220: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
5230: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
5240: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
5250: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
5260: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
5270: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
5280: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
5290: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
52a0: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
52b0: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
52c0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
52d0: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
52e0: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
52f0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
5300: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
5310: 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  cess..*/.#ifndef
5320: 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65   _SQLITE3_H_.#de
5330: 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f  fine _SQLITE3_H_
5340: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
5350: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
5360: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
5370: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
5380: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
5390: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
53a0: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
53b0: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65   C++..*/.#if 0.e
53c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
53d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  if.../*.** Add t
53e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
53f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a  erride 'extern'.
5400: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
5410: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
5420: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
5430: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23  extern.#endif..#
5440: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50  ifndef SQLITE_AP
5450: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
5460: 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f  E_API.#endif.../
5470: 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70  *.** These no-op
5480: 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64   macros are used
5490: 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74   in front of int
54a0: 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20  erfaces to mark 
54b0: 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  those.** interfa
54c0: 63 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65  ces as either de
54d0: 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65  precated or expe
54e0: 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61  rimental.  New a
54f0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
5500: 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65  hould not use de
5510: 70 72 65 63 61 74 65 64 20 69 6e 74 65 72 66 61  precated interfa
5520: 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 73  ces - they are s
5530: 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77  upport for backw
5540: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
5550: 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70  ility only.  App
5560: 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73  lication writers
5570: 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65   should be aware
5580: 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d   that.** experim
5590: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
55a0: 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20   are subject to 
55b0: 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20  change in point 
55c0: 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
55d0: 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65  These macros use
55e0: 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20  d to resolve to 
55f0: 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66  various kinds of
5600: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
5610: 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65  that.** would ge
5620: 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d  nerate warning m
5630: 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65  essages when the
5640: 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75  y were used.  Bu
5650: 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c  t that.** compil
5660: 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75  er magic ended u
5670: 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63  p generating suc
5680: 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75  h a flurry of bu
5690: 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61  g reports.** tha
56a0: 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20  t we have taken 
56b0: 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67  it all out and g
56c0: 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e  one back to usin
56d0: 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70  g simple.** noop
56e0: 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66   macros..*/.#def
56f0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45  ine SQLITE_DEPRE
5700: 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51  CATED.#define SQ
5710: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
5720: 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20  L../*.** Ensure 
5730: 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65  these symbols we
5740: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
5750: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
5760: 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a  header file..*/.
5770: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
5780: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51  RSION.# undef SQ
5790: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e  LITE_VERSION.#en
57a0: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54  dif.#ifdef SQLIT
57b0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
57c0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
57d0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
57e0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
57f0: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
5800: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
5810: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a  ion Numbers.**.*
5820: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f  * ^(The [SQLITE_
5830: 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72  VERSION] C prepr
5840: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e  ocessor macro in
5850: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68   the sqlite3.h h
5860: 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74  eader.** evaluat
5870: 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c  es to a string l
5880: 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74  iteral that is t
5890: 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  he SQLite versio
58a0: 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  n in the.** form
58b0: 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65  at "X.Y.Z" where
58c0: 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20   X is the major 
58d0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
58e0: 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20  always 3 for.** 
58f0: 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69  SQLite3) and Y i
5900: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73  s the minor vers
5910: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a  ion number and Z
5920: 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20   is the release 
5930: 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54  number.)^.** ^(T
5940: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
5950: 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65  ON_NUMBER] C pre
5960: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
5970: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69  resolves to an i
5980: 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74  nteger.** with t
5990: 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30  he value (X*1000
59a0: 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a  000 + Y*1000 + Z
59b0: 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e  ) where X, Y, an
59c0: 64 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65  d Z are the same
59d0: 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64  .** numbers used
59e0: 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   in [SQLITE_VERS
59f0: 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53  ION].)^.** The S
5a00: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
5a10: 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76  MBER for any giv
5a20: 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  en release of SQ
5a30: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a  Lite will also.*
5a40: 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  * be larger than
5a50: 20 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f   the release fro
5a60: 6d 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65  m which it is de
5a70: 72 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59  rived.  Either Y
5a80: 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64   will.** be held
5a90: 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20   constant and Z 
5aa0: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e  will be incremen
5ab0: 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69  ted or else Y wi
5ac0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
5ad0: 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20  d.** and Z will 
5ae0: 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f  be reset to zero
5af0: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65  ..**.** Since ve
5b00: 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51  rsion 3.6.18, SQ
5b10: 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65  Lite source code
5b20: 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64   has been stored
5b30: 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72   in the.** <a hr
5b40: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66  ef="http://www.f
5b50: 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e  ossil-scm.org/">
5b60: 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61  Fossil configura
5b70: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a  tion management.
5b80: 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20  ** system</a>.  
5b90: 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  ^The SQLITE_SOUR
5ba0: 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c  CE_ID macro eval
5bb0: 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74  uates to.** a st
5bc0: 72 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74  ring which ident
5bd0: 69 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c  ifies a particul
5be0: 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53  ar check-in of S
5bf0: 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20  QLite.** within 
5c00: 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  its configuratio
5c10: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73  n management sys
5c20: 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  tem.  ^The SQLIT
5c30: 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73  E_SOURCE_ID.** s
5c40: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74  tring contains t
5c50: 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  he date and time
5c60: 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e   of the check-in
5c70: 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48   (UTC) and an SH
5c80: 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68  A1.** hash of th
5c90: 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20  e entire source 
5ca0: 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tree..**.** See 
5cb0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c  also: [sqlite3_l
5cc0: 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a  ibversion()],.**
5cd0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
5ce0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20  sion_number()], 
5cf0: 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  [sqlite3_sourcei
5d00: 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
5d10: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
5d20: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
5d30: 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  d()]..*/.#define
5d40: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20   SQLITE_VERSION 
5d50: 20 20 20 20 20 20 20 22 33 2e 37 2e 31 36 22 0a         "3.7.16".
5d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
5d70: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30  ERSION_NUMBER 30
5d80: 30 37 30 31 36 0a 23 64 65 66 69 6e 65 20 53 51  07016.#define SQ
5d90: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
5da0: 20 20 20 20 22 32 30 31 33 2d 30 31 2d 31 37 20      "2013-01-17 
5db0: 30 33 3a 31 38 3a 33 38 20 36 35 32 32 33 33 64  03:18:38 652233d
5dc0: 36 34 36 32 33 36 64 33 66 62 63 61 36 32 39 38  646236d3fbca6298
5dd0: 31 33 62 32 30 64 30 37 35 66 30 30 66 33 65 64  13b20d075f00f3ed
5de0: 36 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  6"../*.** CAPI3R
5df0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
5e00: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
5e10: 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  bers.** KEYWORDS
5e20: 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  : sqlite3_versio
5e30: 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  n, sqlite3_sourc
5e40: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
5e50: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
5e60: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
5e70: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
5e80: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
5e90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
5ea0: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
5eb0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
5ec0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
5ed0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
5ee0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
5ef0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
5f00: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
5f10: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
5f20: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
5f30: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
5f40: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
5f50: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
5f60: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
5f70: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
5f80: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
5f90: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
5fa0: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
5fb0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
5fc0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
5fd0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
5fe0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
5ff0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
6000: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
6010: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
6020: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
6030: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
6040: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
6050: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
6060: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
6070: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
6080: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
6090: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
60a0: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
60b0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
60c0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
60d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
60e0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
60f0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
6100: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
6110: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
6120: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
6130: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
6140: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
6150: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
6160: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
6170: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
6180: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
6190: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
61a0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
61b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
61c0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
61d0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
61e0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
61f0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
6200: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
6210: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
6220: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
6230: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
6240: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
6250: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
6260: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
6270: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
6280: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
6290: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
62a0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
62b0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
62c0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
62d0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
62e0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
62f0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
6300: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
6310: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
6320: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
6330: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
6340: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
6350: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
6360: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
6370: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
6380: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
6390: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
63a0: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
63b0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
63c0: 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76  t char sqlite3_v
63d0: 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54  ersion[] = SQLIT
63e0: 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54  E_VERSION;.SQLIT
63f0: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
6400: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
6410: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  sion(void);.SQLI
6420: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
6430: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
6440: 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  eid(void);.SQLIT
6450: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
6460: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
6470: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ber(void);../*.*
6480: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
6490: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d  Time Library Com
64a0: 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  pilation Options
64b0: 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a   Diagnostics.**.
64c0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
64d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
64e0: 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  ed() function re
64f0: 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a  turns 0 or 1 .**
6500: 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74   indicating whet
6510: 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65  her the specifie
6520: 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66  d option was def
6530: 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70  ined at .** comp
6540: 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  ile time.  ^The 
6550: 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d  SQLITE_ prefix m
6560: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72  ay be omitted fr
6570: 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f  om the .** optio
6580: 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f  n name passed to
6590: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
65a0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20  option_used().  
65b0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
65c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
65d0: 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  n_get() function
65e0: 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e   allows iteratin
65f0: 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69  g.** over the li
6600: 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68  st of options th
6610: 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20  at were defined 
6620: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20  at compile time 
6630: 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20  by.** returning 
6640: 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65  the N-th compile
6650: 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72   time option str
6660: 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f  ing.  ^If N is o
6670: 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20  ut of range,.** 
6680: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
6690: 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75  ption_get() retu
66a0: 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
66b0: 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  er.  ^The SQLITE
66c0: 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20  _ .** prefix is 
66d0: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79  omitted from any
66e0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
66f0: 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
6700: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6710: 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70  et()..**.** ^Sup
6720: 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61  port for the dia
6730: 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  gnostic function
6740: 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  s sqlite3_compil
6750: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a  eoption_used().*
6760: 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
6770: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
6780: 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  ) may be omitted
6790: 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74   by specifying t
67a0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
67b0: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f  MIT_COMPILEOPTIO
67c0: 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20  N_DIAGS] option 
67d0: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
67e0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
67f0: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b   SQL functions [
6800: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
6810: 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64  tion_used()] and
6820: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  .** [sqlite_comp
6830: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d  ileoption_get()]
6840: 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c   and the [compil
6850: 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61  e_options pragma
6860: 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  ]..*/.#ifndef SQ
6870: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
6880: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51  EOPTION_DIAGS.SQ
6890: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
68a0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
68b0: 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68  on_used(const ch
68c0: 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53  ar *zOptName);.S
68d0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
68e0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
68f0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
6900: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
6910: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6920: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
6930: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
6940: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
6950: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
6960: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
6970: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
6980: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
6990: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
69a0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
69b0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
69c0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
69d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
69e0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
69f0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
6a00: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
6a10: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
6a20: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
6a30: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
6a40: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
6a50: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
6a60: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
6a70: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
6a80: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
6a90: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
6aa0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
6ab0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
6ac0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
6ad0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
6ae0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
6af0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
6b00: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
6b10: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
6b20: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
6b30: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
6b40: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
6b50: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
6b60: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
6b70: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
6b80: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
6b90: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
6ba0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
6bb0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
6bc0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
6bd0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
6be0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
6bf0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
6c00: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
6c10: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
6c20: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
6c30: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
6c40: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
6c50: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
6c60: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
6c70: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
6c80: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
6c90: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
6ca0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
6cb0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
6cc0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
6cd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
6ce0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
6cf0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
6d00: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
6d10: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
6d20: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
6d30: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
6d40: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
6d50: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
6d60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
6d70: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
6d80: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
6d90: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
6da0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
6db0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
6dc0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
6dd0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
6de0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
6df0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
6e00: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
6e10: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
6e20: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
6e30: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
6e40: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
6e50: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
6e60: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
6e70: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
6e80: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
6e90: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
6ea0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
6eb0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
6ec0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
6ed0: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
6ee0: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
6ef0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
6f00: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
6f10: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
6f20: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
6f30: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
6f40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
6f50: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
6f60: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
6f70: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
6f80: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
6f90: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
6fa0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
6fb0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
6fc0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
6fd0: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
6fe0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
6ff0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
7000: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
7010: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
7020: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
7030: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
7040: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
7050: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
7060: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
7070: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
7080: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7090: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
70a0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
70b0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
70c0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
70d0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
70e0: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
70f0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
7100: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
7110: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
7120: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
7130: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
7140: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
7150: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
7160: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
7170: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
7180: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
7190: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
71a0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
71b0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
71c0: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
71d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
71e0: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
71f0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
7200: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
7210: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
7220: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
7230: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
7240: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
7250: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
7260: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
7270: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
7280: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
7290: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
72a0: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
72b0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
72c0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
72d0: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
72e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
72f0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
7300: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
7310: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
7320: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
7330: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
7340: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
7350: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
7360: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
7370: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
7380: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
7390: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
73a0: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
73b0: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
73c0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
73d0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
73e0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
73f0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
7400: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
7410: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
7420: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
7430: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
7440: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
7450: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
7460: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
7470: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
7480: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
7490: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
74a0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
74b0: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
74c0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
74d0: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
74e0: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
74f0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
7500: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
7510: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
7520: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
7530: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
7540: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
7550: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
7560: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
7570: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
7580: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
7590: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
75a0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
75b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
75c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49  ef unsigned SQLI
75d0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
75e0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
75f0: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
7600: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
7610: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
7620: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
7630: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
7640: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
7650: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
7660: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
7670: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
7680: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
7690: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
76a0: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
76b0: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
76c0: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64  64;.#endif.typed
76d0: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  ef sqlite_int64 
76e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74  sqlite3_int64;.t
76f0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69  ypedef sqlite_ui
7700: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e  nt64 sqlite3_uin
7710: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63  t64;../*.** If c
7720: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70  ompiling for a p
7730: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61  rocessor that la
7740: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  cks floating poi
7750: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73  nt support,.** s
7760: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65  ubstitute intege
7770: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70  r for floating-p
7780: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  oint..*/.#ifdef 
7790: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
77a0: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
77b0: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
77c0: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
77d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
77e0: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
77f0: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
7800: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
7810: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71  3_close() and sq
7820: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
7830: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
7840: 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72  structors.** for
7850: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
7860: 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73  bject..** ^Calls
7870: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   to sqlite3_clos
7880: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
7890: 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72  close_v2() retur
78a0: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 0a 2a  n SQLITE_OK if.*
78b0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  * the [sqlite3] 
78c0: 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73  object is succes
78d0: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64  sfully destroyed
78e0: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61   and all associa
78f0: 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73  ted.** resources
7900: 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64   are deallocated
7910: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
7920: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7930: 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65  ion is associate
7940: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
7950: 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  ed prepared.** s
7960: 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66  tatements or unf
7970: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
7980: 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74  backup objects t
7990: 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  hen sqlite3_clos
79a0: 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76  e().** will leav
79b0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
79c0: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61  onnection open a
79d0: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
79e0: 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20  E_BUSY]..** ^If 
79f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
7a00: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
7a10: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72  h unfinalized pr
7a20: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
7a30: 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69 6e 69 73  s.** and unfinis
7a40: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  hed sqlite3_back
7a50: 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ups, then the da
7a60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7a70: 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20  n becomes.** an 
7a80: 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65  unusable "zombie
7a90: 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74  " which will aut
7aa0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65  omatically be de
7ab0: 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74  allocated when t
7ac0: 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61  he.** last prepa
7ad0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
7ae0: 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68   finalized or th
7af0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62  e last sqlite3_b
7b00: 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69  ackup is.** fini
7b10: 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  shed.  The sqlit
7b20: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e  e3_close_v2() in
7b30: 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e  terface is inten
7b40: 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68  ded for use with
7b50: 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67  .** host languag
7b60: 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62  es that are garb
7b70: 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61  age collected, a
7b80: 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64  nd where the ord
7b90: 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64  er in which.** d
7ba0: 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63  estructors are c
7bb0: 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61  alled is arbitra
7bc0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ry..**.** Applic
7bd0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73  ations should [s
7be0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
7bf0: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
7c00: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
7c10: 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ents],.** [sqlit
7c20: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20  e3_blob_close | 
7c30: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42  close] all [BLOB
7c40: 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a   handles], and .
7c50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
7c60: 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69  up_finish | fini
7c70: 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33  sh] all [sqlite3
7c80: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
7c90: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
7ca0: 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ith the [sqlite3
7cb0: 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74  ] object prior t
7cc0: 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  o attempting to 
7cd0: 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74  close the object
7ce0: 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65  .  ^If.** sqlite
7cf0: 33 5f 63 6c 6f 73 65 28 29 20 69 73 20 63 61 6c  3_close() is cal
7d00: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
7d10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
7d20: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
7d30: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
7d40: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
7d50: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
7d60: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
7d70: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
7d80: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
7d90: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
7da0: 20 62 75 74 20 74 68 65 20 64 65 61 6c 6c 6f 63   but the dealloc
7db0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f  ation.** of reso
7dc0: 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65  urces is deferre
7dd0: 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65  d until all [pre
7de0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
7df0: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
7e00: 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  ],.** and [sqlit
7e10: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
7e20: 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74  ts are also dest
7e30: 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  royed..**.** ^If
7e40: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
7e50: 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65  ject is destroye
7e60: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61  d while a transa
7e70: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a  ction is open,.*
7e80: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  * the transactio
7e90: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  n is automatical
7ea0: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
7eb0: 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61  **.** The C para
7ec0: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
7ed0: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20  3_close(C)] and 
7ee0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
7ef0: 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  2(C)].** must be
7f00: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a   either a NULL.*
7f10: 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20  * pointer or an 
7f20: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
7f30: 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65   pointer obtaine
7f40: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
7f50: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
7f60: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
7f70: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
7f80: 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e  pen_v2()], and n
7f90: 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c  ot previously cl
7fa0: 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  osed..** ^Callin
7fb0: 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  g sqlite3_close(
7fc0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ) or sqlite3_clo
7fd0: 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e  se_v2() with a N
7fe0: 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61  ULL pointer.** a
7ff0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72  rgument is a har
8000: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
8010: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
8020: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c  qlite3_close(sql
8030: 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
8040: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
8050: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
8060: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
8070: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
8080: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
8090: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
80a0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
80b0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
80c0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
80d0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
80e0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
80f0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
8100: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
8110: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
8120: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
8130: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
8140: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
8150: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
8160: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
8170: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8180: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
8190: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
81a0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
81b0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
81c0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
81d0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
81e0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
81f0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
8200: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
8210: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
8220: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
8230: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
8240: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
8250: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
8260: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
8270: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
8280: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
8290: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
82a0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
82b0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
82c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
82d0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
82e0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
82f0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
8300: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8310: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
8320: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
8330: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
8340: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
8350: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
8360: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
8370: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
8380: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
8390: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
83a0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
83b0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
83c0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
83d0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
83e0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
83f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
8400: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
8410: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
8420: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
8430: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
8440: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
8450: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
8460: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
8470: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
8480: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
8490: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
84a0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
84b0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
84c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
84d0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
84e0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
84f0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
8500: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
8510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
8520: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
8530: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
8540: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
8550: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
8560: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
8570: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
8580: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
8590: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
85a0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
85b0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
85c0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
85d0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
85e0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
85f0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
8600: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
8610: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
8620: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
8630: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
8640: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
8650: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
8660: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
8670: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
8680: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
8690: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
86a0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
86b0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
86c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
86d0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
86e0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
86f0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
8700: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
8710: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
8720: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
8730: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
8740: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
8750: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
8760: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
8770: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
8780: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
8790: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
87a0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
87b0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
87c0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
87d0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
87e0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
87f0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
8800: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
8810: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
8820: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
8830: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
8840: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
8850: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
8860: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
8870: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
8880: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
8890: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
88a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
88b0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
88c0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
88d0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
88e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
88f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
8900: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
8910: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
8920: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
8930: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
8940: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
8950: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
8960: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
8970: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
8980: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
8990: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
89a0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
89b0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
89c0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
89d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
89e0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
89f0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
8a00: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
8a10: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
8a20: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
8a30: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
8a40: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
8a50: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
8a60: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
8a70: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
8a80: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
8a90: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
8aa0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
8ab0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
8ac0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
8ad0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
8ae0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
8af0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
8b00: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
8b10: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
8b20: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
8b30: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
8b40: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
8b50: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
8b60: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
8b70: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
8b80: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
8b90: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
8ba0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
8bb0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
8bc0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
8bd0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
8be0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
8bf0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
8c00: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
8c10: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
8c20: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
8c30: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
8c40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8c50: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
8c60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
8c70: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74  t not close [dat
8c80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8c90: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
8ca0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
8cb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
8cc0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
8cd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8ce0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
8cf0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
8d00: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
8d10: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
8d20: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
8d30: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
8d40: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
8d50: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
8d60: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
8d70: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
8d80: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
8d90: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
8da0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
8db0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
8dc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8dd0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
8de0: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
8df0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
8e00: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
8e10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
8e20: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
8e30: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
8e40: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
8e50: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
8e60: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
8e70: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
8e80: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
8e90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8ea0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
8eb0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
8ec0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
8ed0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
8ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8ef0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
8f00: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
8f10: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
8f20: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
8f30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
8f40: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
8f50: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
8f60: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
8f70: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
8f80: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
8f90: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
8fa0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
8fb0: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
8fc0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
8fd0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
8fe0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
8ff0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
9000: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
9010: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
9020: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
9030: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
9040: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
9050: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
9060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
9070: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
9080: 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b  ult codes],.** [
9090: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
90a0: 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51 4c  conflict()] [SQL
90b0: 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
90c0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f  esult codes]..*/
90d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
90e0: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
90f0: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
9100: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
9110: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
9120: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
9130: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
9140: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
9150: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
9160: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
9170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
9180: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
9190: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
91a0: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
91b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
91c0: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
91d0: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
91e0: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
91f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
9200: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
9210: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
9220: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
9230: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
9240: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
9250: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
9260: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
9270: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
9280: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
9290: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
92a0: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
92b0: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
92c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
92d0: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
92e0: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
92f0: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
9300: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
9310: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
9320: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
9330: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
9340: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
9350: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
9360: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
9370: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
9380: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
9390: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
93a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
93b0: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
93c0: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
93d0: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
93e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
93f0: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
9400: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
9410: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
9420: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
9430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
9440: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
9450: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
9460: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
9470: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
9480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
9490: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
94a0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
94b0: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
94c0: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
94d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
94e0: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
94f0: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
9500: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
9520: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
9530: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
9540: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
9550: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
9560: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
9570: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61    16   /* Databa
9580: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23  se is empty */.#
9590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
95a0: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
95b0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
95c0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
95d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
95e0: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
95f0: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
9600: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
9610: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
9620: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
9630: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
9640: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
9650: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
9660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9670: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
9680: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
9690: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
96a0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
96b0: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
96c0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
96d0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
96e0: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
96f0: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
9700: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
9710: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
9720: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
9730: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
9740: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
9750: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
9760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9770: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
9780: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
9790: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
97a0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
97b0: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
97c0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
97d0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
97e0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
97f0: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
9800: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
9810: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
9820: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
9830: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
9840: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
9850: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
9860: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
9870: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
9880: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
9890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
98a0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
98b0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
98c0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
98d0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
98e0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
98f0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
9900: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
9910: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
9920: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
9930: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
9940: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
9950: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
9960: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
9970: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
9980: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
9990: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
99a0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
99b0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
99c0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
99d0: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
99e0: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
99f0: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
9a00: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
9a10: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
9a20: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
9a30: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
9a40: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
9a50: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
9a60: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
9a70: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
9a80: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
9a90: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
9aa0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
9ab0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
9ac0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
9ad0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
9ae0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
9af0: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
9b00: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
9b10: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
9b20: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
9b30: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
9b40: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
9b50: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
9b60: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
9b70: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
9b80: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
9b90: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
9ba0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
9bb0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9bc0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
9bd0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
9be0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
9bf0: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
9c00: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
9c10: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
9c20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
9c30: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
9c40: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
9c50: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
9c60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
9c70: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
9c80: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
9c90: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
9ca0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
9cb0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
9cc0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
9cd0: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
9ce0: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
9cf0: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
9d00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
9d10: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
9d20: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
9d30: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
9d40: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
9d50: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
9d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9d70: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
9d80: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9d90: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
9da0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
9db0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
9dc0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
9dd0: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
9de0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9df0: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
9e00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9e10: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
9e20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9e30: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
9e40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9e50: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
9e60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
9e70: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
9e80: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
9e90: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
9ea0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
9eb0: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
9ec0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
9ed0: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
9ee0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
9ef0: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
9f00: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
9f10: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
9f20: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
9f30: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
9f40: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
9f50: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
9f60: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
9f70: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
9f80: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9f90: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
9fa0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
9fb0: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
9fc0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9fd0: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
9fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
9ff0: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
a000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a010: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
a020: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
a030: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
a040: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a050: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
a060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
a070: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
a080: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a090: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
a0a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
a0b0: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
a0c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a0d0: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
a0e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
a0f0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
a100: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a110: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
a120: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
a130: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
a140: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a150: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
a160: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
a170: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
a180: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a190: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
a1a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a1b0: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
a1c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a1d0: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
a1e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a1f0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
a200: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a210: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
a220: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a230: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
a240: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a250: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
a260: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a270: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
a280: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a290: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
a2a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
a2b0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
a2c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a2d0: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
a2e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
a2f0: 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20 28  ETE_NOENT      (
a300: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a310: 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  23<<8)).#define 
a320: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
a330: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
a340: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
a350: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
a360: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
a370: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
a380: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
a390: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
a3a0: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
a3b0: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
a3c0: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
a3d0: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
a3e0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
a3f0: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
a400: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
a410: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
a420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
a430: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
a440: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
a450: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
a460: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
a470: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
a480: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
a490: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
a4a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a4b0: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
a4c0: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
a4d0: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
a4e0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a4f0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
a500: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
a510: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
a520: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
a530: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
a540: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  CK          (SQL
a550: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c  ITE_ABORT | (2<<
a560: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
a570: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
a580: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
a590: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
a5a0: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
a5b0: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
a5c0: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
a5d0: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
a5e0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
a5f0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
a600: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
a610: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
a620: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
a630: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23  en] method..*/.#
a640: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a650: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
a660: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
a670: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
a680: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
a690: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a6a0: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
a6b0: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
a6c0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
a6d0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
a6e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a6f0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
a700: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
a710: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
a720: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
a730: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a740: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
a750: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
a760: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a770: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a780: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
a790: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
a7a0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a7b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a7c0: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
a7d0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
a7e0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a7f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a800: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  EN_URI          
a810: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20      0x00000040  
a820: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
a830: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
a840: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a850: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20  EN_MEMORY       
a860: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20      0x00000080  
a870: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
a880: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
a890: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a8a0: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
a8b0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
a8c0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a8d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a8e0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
a8f0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
a900: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a920: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
a930: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
a940: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a960: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
a970: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
a980: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a9a0: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
a9b0: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
a9c0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a9d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a9e0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
a9f0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
aa00: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
aa10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
aa20: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
aa30: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
aa40: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
aa50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
aa60: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
aa70: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
aa80: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
aa90: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
aaa0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
aab0: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
aac0: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
aad0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
aae0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
aaf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
ab00: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
ab10: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
ab20: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
ab30: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
ab40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
ab50: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
ab60: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
ab70: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
ab80: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
ab90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
aba0: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
abb0: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
abc0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a  /* VFS only */..
abd0: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20  /* Reserved:    
abe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
abf0: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
ac00: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
ac10: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
ac20: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
ac30: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
ac40: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
ac50: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
ac60: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
ac70: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
ac80: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
ac90: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
aca0: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
acb0: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
acc0: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
acd0: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
ace0: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
acf0: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
ad00: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
ad10: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
ad20: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
ad30: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
ad40: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
ad50: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
ad60: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
ad70: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
ad80: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
ad90: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
ada0: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
adb0: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
adc0: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
add0: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
ade0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
adf0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
ae00: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
ae10: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
ae20: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
ae30: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
ae40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
ae50: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
ae60: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
ae70: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
ae80: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
ae90: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
aea0: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
aeb0: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
aec0: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
aed0: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
aee0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
aef0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
af00: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
af10: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
af20: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
af30: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
af40: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
af50: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
af60: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20  * to xWrite().  
af70: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
af80: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
af90: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65  RITE property me
afa0: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65  ans that.** afte
afb0: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69  r reboot followi
afc0: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f  ng a crash or po
afd0: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e  wer loss, the on
afe0: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a  ly bytes in a.**
aff0: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20   file that were 
b000: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61  written at the a
b010: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c  pplication level
b020: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e   might have chan
b030: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ged.** and that 
b040: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20  adjacent bytes, 
b050: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69  even bytes withi
b060: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f  n the same secto
b070: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74  r are.** guarant
b080: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e  eed to be unchan
b090: 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ged..*/.#define 
b0a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
b0b0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
b0c0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
b0d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
b0e0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
b0f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
b100: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
b110: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
b120: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
b130: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
b140: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
b150: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
b160: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
b170: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
b180: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
b190: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
b1a0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
b1b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
b1c0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
b1d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
b1e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b1f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
b200: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
b210: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
b220: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
b230: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
b240: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
b250: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
b260: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
b270: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
b280: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
b290: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
b2a0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
b2b0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
b2c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
b2d0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
b2e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
b2f0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
b300: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
b310: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
b320: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
b330: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
b340: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
b350: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
b360: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
b370: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
b380: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51   Levels.**.** SQ
b390: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
b3a0: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
b3b0: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
b3c0: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
b3d0: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
b3e0: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
b3f0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
b400: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
b410: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
b420: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
b430: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
b440: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
b450: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
b460: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
b470: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
b480: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
b490: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
b4a0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
b4b0: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
b4c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
b4d0: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
b4e0: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
b4f0: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
b500: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a  tion Type Flags.
b510: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
b520: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
b530: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
b540: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
b550: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
b560: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
b570: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ination of.** th
b580: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
b590: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
b5a0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
b5b0: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
b5c0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
b5d0: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
b5e0: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
b5f0: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
b600: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
b610: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
b620: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
b630: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
b640: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
b650: 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77  shed. If the low
b660: 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20  er four bits of 
b670: 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61  the flag.** equa
b680: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  l SQLITE_SYNC_NO
b690: 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  RMAL, that means
b6a0: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
b6b0: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
b6c0: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65  ..** If the lowe
b6d0: 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61  r four bits equa
b6e0: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  l SQLITE_SYNC_FU
b6f0: 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  LL, that means.*
b700: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20  * to use Mac OS 
b710: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
b720: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e   instead of fsyn
b730: 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f  c()..**.** Do no
b740: 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51  t confuse the SQ
b750: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
b760: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
b770: 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77  _FULL flags.** w
b780: 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20  ith the [PRAGMA 
b790: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52  synchronous]=NOR
b7a0: 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  MAL and [PRAGMA 
b7b0: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c  synchronous]=FUL
b7c0: 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20  L.** settings.  
b7d0: 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73  The [synchronous
b7e0: 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69   pragma] determi
b7f0: 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74  nes when calls t
b800: 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56  o the.** xSync V
b810: 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20  FS method occur 
b820: 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66  and applies unif
b830: 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c  ormly across all
b840: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54   platforms..** T
b850: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
b860: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
b870: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
b880: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a   determine how.*
b890: 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72  * energetic or r
b8a0: 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65  igorous or force
b8b0: 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65  ful the sync ope
b8c0: 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a  rations are and.
b8d0: 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64  ** only make a d
b8e0: 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63  ifference on Mac
b8f0: 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66   OSX for the def
b900: 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65  ault SQLite code
b910: 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74  ..** (Third-part
b920: 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  y VFS implementa
b930: 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f  tions might also
b940: 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
b950: 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e  ction.** between
b960: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
b970: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
b980: 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d  YNC_FULL, but am
b990: 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61  ong the.** opera
b9a0: 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74  ting systems nat
b9b0: 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20  ively supported 
b9c0: 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20  by SQLite, only 
b9d0: 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73  Mac OSX.** cares
b9e0: 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65   about the diffe
b9f0: 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69  rence.).*/.#defi
ba00: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  ne SQLITE_SYNC_N
ba10: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30  ORMAL        0x0
ba20: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
ba30: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20  ITE_SYNC_FULL   
ba40: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23         0x00003.#
ba50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
ba60: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20  NC_DATAONLY     
ba70: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20   0x00010../*.** 
ba80: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
ba90: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65  erface Open File
baa0: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e   Handle.**.** An
bab0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
bac0: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
bad0: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
bae0: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  n the .** [sqlit
baf0: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65  e3_vfs | OS inte
bb00: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49  rface layer].  I
bb10: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74  ndividual OS int
bb20: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d  erface.** implem
bb30: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
bb40: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
bb50: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
bb60: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
bb70: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
bb80: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
bb90: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
bba0: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
bbb0: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
bbc0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
bbd0: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
bbe0: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
bbf0: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
bc00: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
bc10: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
bc20: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
bc30: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
bc40: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
bc50: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
bc60: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
bc70: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
bc80: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
bc90: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
bca0: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
bcb0: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
bcc0: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
bcd0: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
bce0: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a  Methods Object.*
bcf0: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20  *.** Every file 
bd00: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73  opened by the [s
bd10: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
bd20: 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74  ] method populat
bd30: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  es an.** [sqlite
bd40: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28  3_file] object (
bd50: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c  or, more commonl
bd60: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  y, a subclass of
bd70: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
bd80: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77  _file] object) w
bd90: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ith a pointer to
bda0: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
bdb0: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  this object..** 
bdc0: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
bdd0: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20  nes the methods 
bde0: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20  used to perform 
bdf0: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f  various operatio
be00: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68  ns.** against th
be10: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72  e open file repr
be20: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b  esented by the [
be30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
be40: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ject..**.** If t
be50: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
be60: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65  xOpen] method se
be70: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  ts the sqlite3_f
be80: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
be90: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f  ment .** to a no
bea0: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
beb0: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
bec0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f  _io_methods.xClo
bed0: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79  se method.** may
bee0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e   be invoked even
bef0: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   if the [sqlite3
bf00: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f  _vfs.xOpen] repo
bf10: 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69  rted that it fai
bf20: 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c  led.  The.** onl
bf30: 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74  y way to prevent
bf40: 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73   a call to xClos
bf50: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  e following a fa
bf60: 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66  iled [sqlite3_vf
bf70: 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66  s.xOpen].** is f
bf80: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
bf90: 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65  vfs.xOpen] to se
bfa0: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
bfb0: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
bfc0: 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a  ent.** to NULL..
bfd0: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
bfe0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
bff0: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
c000: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
c010: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
c020: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
c030: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
c040: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
c050: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
c060: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
c070: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
c080: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
c090: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
c0a0: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
c0b0: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
c0c0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
c0d0: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
c0e0: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
c0f0: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
c100: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
c110: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
c120: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
c130: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
c140: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
c150: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
c160: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
c170: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
c180: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
c190: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c1a0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
c1b0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c1c0: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
c1d0: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
c1e0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
c1f0: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
c200: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
c210: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
c220: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
c230: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
c240: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
c250: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
c260: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
c270: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c280: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
c290: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
c2a0: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
c2b0: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
c2c0: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
c2d0: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
c2e0: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
c2f0: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
c300: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
c310: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
c320: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
c330: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
c340: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
c350: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
c360: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
c370: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
c380: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
c390: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
c3a0: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
c3b0: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
c3c0: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
c3d0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
c3e0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
c3f0: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
c400: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
c410: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
c420: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
c430: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
c440: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
c450: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
c460: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
c470: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
c480: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
c490: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
c4a0: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
c4b0: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
c4c0: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
c4d0: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
c4e0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
c4f0: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
c500: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
c510: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
c520: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
c530: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
c540: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
c550: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
c560: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
c570: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
c580: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
c590: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
c5a0: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
c5b0: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
c5c0: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
c5d0: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
c5e0: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51  wn use..** A [SQ
c5f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
c600: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
c610: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
c620: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
c630: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
c640: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
c650: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
c660: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
c670: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
c680: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
c690: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
c6a0: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
c6b0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
c6c0: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
c6d0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
c6e0: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
c6f0: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
c700: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
c710: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
c720: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
c730: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
c740: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
c750: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
c760: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
c770: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
c780: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
c790: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
c7a0: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
c7b0: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
c7c0: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
c7d0: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
c7e0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
c7f0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
c800: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
c810: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
c820: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
c830: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
c840: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
c850: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
c860: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c870: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
c880: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
c890: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
c8a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c8b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
c8c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c8d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
c8e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c8f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
c900: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c910: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
c920: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c930: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
c940: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c950: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
c960: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
c970: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
c980: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
c990: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
c9a0: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
c9b0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
c9c0: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
c9d0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
c9e0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
c9f0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
ca00: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
ca10: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
ca20: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
ca30: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
ca40: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
ca50: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
ca60: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
ca70: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
ca80: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
ca90: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
caa0: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
cab0: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
cac0: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
cad0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
cae0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
caf0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
cb00: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
cb10: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
cb20: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
cb30: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
cb40: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
cb50: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
cb60: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
cb70: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
cb80: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
cb90: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
cba0: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
cbb0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
cbc0: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
cbd0: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
cbe0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
cbf0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
cc00: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
cc10: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
cc20: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
cc30: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
cc40: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
cc50: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
cc60: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
cc70: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
cc80: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
cc90: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
cca0: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
ccb0: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
ccc0: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
ccd0: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
cce0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
ccf0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
cd00: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
cd10: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
cd20: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
cd30: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
cd40: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
cd50: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
cd60: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
cd70: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
cd80: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
cd90: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
cda0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
cdb0: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
cdc0: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
cdd0: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
cde0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
cdf0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
ce00: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
ce10: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
ce20: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
ce30: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
ce40: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
ce50: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
ce60: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
ce70: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
ce80: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
ce90: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
cea0: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
ceb0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
cec0: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
ced0: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
cee0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
cef0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
cf00: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
cf10: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
cf20: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
cf30: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
cf40: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
cf50: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
cf60: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
cf70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
cf80: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
cf90: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
cfa0: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
cfb0: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
cfc0: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
cfd0: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
cfe0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
cff0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
d000: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
d010: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
d020: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
d030: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
d040: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
d050: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
d060: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
d070: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
d080: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
d090: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
d0a0: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
d0b0: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
d0c0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
d0d0: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
d0e0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
d0f0: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
d100: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
d110: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
d120: 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 2 */.  /* Addi
d130: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
d140: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
d150: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
d160: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
d170: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
d180: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
d190: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  des.**.** These 
d1a0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
d1b0: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
d1c0: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
d1d0: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
d1e0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
d1f0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
d200: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
d210: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
d220: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
d230: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  e..**.** The [SQ
d240: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
d250: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
d260: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
d270: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
d280: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
d290: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
d2a0: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20  od to write the 
d2b0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66  current state of
d2c0: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e  .** the lock (on
d2d0: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  e of [SQLITE_LOC
d2e0: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  K_NONE], [SQLITE
d2f0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
d300: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  * [SQLITE_LOCK_R
d310: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54  ESERVED], [SQLIT
d320: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
d330: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   or [SQLITE_LOCK
d340: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20  _EXCLUSIVE]).** 
d350: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  into an integer 
d360: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72  that the pArg ar
d370: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
d380: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74  . This capabilit
d390: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
d3a0: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
d3b0: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
d3c0: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
d3d0: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69  SQLITE_TEST.** i
d3e0: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75  s defined..** <u
d3f0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
d400: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
d410: 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NT]].** The [SQL
d420: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
d430: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  INT] opcode is u
d440: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f  sed by SQLite to
d450: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a   give the VFS.**
d460: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66   layer a hint of
d470: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64   how large the d
d480: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
d490: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72  l grow to be dur
d4a0: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  ing the.** curre
d4b0: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  nt transaction. 
d4c0: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
d4d0: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  t guaranteed to 
d4e0: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20  be accurate but 
d4f0: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63  it.** is often c
d500: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72  lose.  The under
d510: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20  lying VFS might 
d520: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c  choose to preall
d530: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a  ocate database.*
d540: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73  * file space bas
d550: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ed on this hint 
d560: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70  in order to help
d570: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64   writes to the d
d580: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
d590: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a  run faster..**.*
d5a0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
d5b0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
d5c0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
d5d0: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
d5e0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
d5f0: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
d600: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
d610: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
d620: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
d630: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
d640: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
d650: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
d660: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
d670: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
d680: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
d690: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
d6a0: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
d6b0: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
d6c0: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
d6d0: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
d6e0: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
d6f0: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
d700: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
d710: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
d720: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
d730: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
d740: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
d750: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
d760: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
d770: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
d780: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
d790: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c  systems..**.** <
d7a0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
d7b0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d  L_FILE_POINTER]]
d7c0: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
d7d0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
d7e0: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
d7f0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
d800: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
d810: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
d820: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
d830: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  d with a particu
d840: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
d850: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
d860: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
d870: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f  le_control()] do
d880: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  cumentation for.
d890: 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
d8a0: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
d8b0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d8c0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
d8d0: 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  ]].** ^(The [SQL
d8e0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
d8f0: 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69  MITTED] opcode i
d900: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
d910: 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c  rnally by.** SQL
d920: 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  ite and sent to 
d930: 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61  all VFSes in pla
d940: 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20  ce of a call to 
d950: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
d960: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74  .** when the dat
d970: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d980: 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e   has [PRAGMA syn
d990: 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f  chronous] set to
d9a0: 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20   OFF.)^.** Some 
d9b0: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
d9c0: 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  s need this sign
d9d0: 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f  al in order to o
d9e0: 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79  perate correctly
d9f0: 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41  .** when [PRAGMA
da00: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50   synchronous | P
da10: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
da20: 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62  s=OFF] is set, b
da30: 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65  ut most .** VFSe
da40: 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  s do not need th
da50: 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68  is signal and sh
da60: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
da70: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
da80: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
da90: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
daa0: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
dab0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
dac0: 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  this.** opcode a
dad0: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
dae0: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
daf0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
db00: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a  ialized VFSes.**
db10: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
db20: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
db30: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
db40: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
db50: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
db60: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
db70: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
db80: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
db90: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
dba0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
dbb0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
dbc0: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
dbd0: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
dbe0: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
dbf0: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
dc00: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
dc10: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
dc20: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
dc30: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
dc40: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
dc50: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
dc60: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
dc70: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
dc80: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
dc90: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
dca0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
dcb0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
dcc0: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
dcd0: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
dce0: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
dcf0: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
dd00: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
dd10: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
dd20: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
dd30: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
dd40: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
dd50: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
dd60: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
dd70: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
dd80: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
dd90: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
dda0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
ddb0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
ddc0: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
ddd0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
dde0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
ddf0: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
de00: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
de10: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
de20: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
de30: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
de40: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
de50: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
de60: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
de70: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
de80: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
de90: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
dea0: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
deb0: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
dec0: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
ded0: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
dee0: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
def0: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
df00: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
df10: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
df20: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
df30: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
df40: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
df50: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
df60: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
df70: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
df80: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
df90: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
dfa0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
dfb0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
dfc0: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
dfd0: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
dfe0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
dff0: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
e000: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
e010: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
e020: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
e030: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
e040: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
e050: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
e060: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
e070: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
e080: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
e090: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
e0a0: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
e0b0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
e0c0: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
e0d0: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
e0e0: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
e0f0: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
e100: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
e110: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
e120: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
e130: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
e140: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
e150: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
e160: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
e170: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
e180: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
e190: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
e1a0: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
e1b0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
e1c0: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
e1d0: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
e1e0: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
e1f0: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
e200: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
e210: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
e220: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
e230: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
e240: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
e250: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
e260: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
e270: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
e280: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
e290: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
e2a0: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
e2b0: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
e2c0: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
e2d0: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
e2e0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
e2f0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
e300: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
e310: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
e320: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
e330: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
e340: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
e350: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
e360: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
e370: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
e380: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
e390: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
e3a0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
e3b0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
e3c0: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
e3d0: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
e3e0: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
e3f0: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
e400: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
e410: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
e420: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
e430: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
e440: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
e450: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
e460: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
e470: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
e480: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
e490: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
e4a0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
e4b0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
e4c0: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
e4d0: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
e4e0: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
e4f0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
e500: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
e510: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
e520: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
e530: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
e540: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
e550: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
e560: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
e570: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
e580: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
e590: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
e5a0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
e5b0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
e5c0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
e5d0: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
e5e0: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
e5f0: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
e600: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
e610: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
e620: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
e630: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
e640: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
e650: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
e660: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
e670: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
e680: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
e690: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
e6a0: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
e6b0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
e6c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
e6d0: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
e6e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
e6f0: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
e700: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
e710: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
e720: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
e730: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
e740: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
e750: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
e760: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
e770: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
e780: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
e790: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
e7a0: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
e7b0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
e7c0: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
e7d0: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
e7e0: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
e7f0: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
e800: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
e810: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
e820: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
e830: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
e840: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
e850: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
e860: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
e870: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
e880: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
e890: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
e8a0: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
e8b0: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
e8c0: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
e8d0: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
e8e0: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
e8f0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
e900: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
e910: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
e920: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
e930: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
e940: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
e950: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
e960: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
e970: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
e980: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
e990: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
e9a0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
e9b0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
e9c0: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
e9d0: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
e9e0: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
e9f0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
ea00: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
ea10: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
ea20: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
ea30: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
ea40: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
ea50: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
ea60: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
ea70: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
ea80: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
ea90: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
eaa0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
eab0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
eac0: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
ead0: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
eae0: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
eaf0: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
eb00: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
eb10: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
eb20: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
eb30: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
eb40: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
eb50: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
eb60: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
eb70: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
eb80: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
eb90: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
eba0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
ebb0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
ebc0: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
ebd0: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
ebe0: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
ebf0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
ec00: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
ec10: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
ec20: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
ec30: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
ec40: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
ec50: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
ec60: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
ec70: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
ec80: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
ec90: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
eca0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
ecb0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ecc0: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
ecd0: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
ece0: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
ecf0: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
ed00: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
ed10: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
ed20: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
ed30: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
ed40: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
ed50: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
ed60: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
ed70: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
ed80: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
ed90: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
eda0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
edb0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
edc0: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
edd0: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49  d statement.  ^I
ede0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
edf0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
ee00: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
ee10: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
ee20: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
ee30: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
ee40: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
ee50: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
ee60: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
ee70: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
ee80: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
ee90: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
eea0: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
eeb0: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
eec0: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
eed0: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
eee0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
eef0: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
ef00: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
ef10: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
ef20: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
ef30: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
ef40: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
ef50: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
ef60: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
ef70: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
ef80: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
ef90: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
efa0: 20 5e 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74   ^This file-cont
efb0: 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  rol may be invok
efc0: 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f 6e 20  ed by SQLite on 
efd0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
efe0: 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72  e handle.** shor
eff0: 74 6c 79 20 61 66 74 65 72 20 69 74 20 69 73 20  tly after it is 
f000: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
f010: 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63 75 73  to provide a cus
f020: 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61 63 63  tom VFS with acc
f030: 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f  ess.** to the co
f040: 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79 2d 68  nnections busy-h
f050: 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e  andler callback.
f060: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
f070: 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64 20 2a   of type (void *
f080: 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79  *).** - an array
f090: 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20 2a 29   of two (void *)
f0a0: 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66 69 72   values. The fir
f0b0: 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63 74 75  st (void *) actu
f0c0: 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74  ally points.** t
f0d0: 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
f0e0: 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28 76 6f  type (int (*)(vo
f0f0: 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72  id *)). In order
f100: 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 20 63   to invoke the c
f110: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75  onnections.** bu
f120: 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68 69 73  sy-handler, this
f130: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64   function should
f140: 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
f150: 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76 6f 69   the second (voi
f160: 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61  d *) in.** the a
f170: 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e 6c 79  rray as the only
f180: 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20 69 74   argument. If it
f190: 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
f1a0: 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70 65 72  o, then the oper
f1b0: 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20  ation.** should 
f1c0: 62 65 20 72 65 74 72 69 65 64 2e 20 49 66 20 69  be retried. If i
f1d0: 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  t returns zero, 
f1e0: 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53 20 73  the custom VFS s
f1f0: 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68  hould abandon th
f200: 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f 70 65  e.** current ope
f210: 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  ration..**.** <l
f220: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
f230: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a  _TEMPFILENAME]].
f240: 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20  ** ^Application 
f250: 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 69 73 20  can invoke this 
f260: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 74 6f 20  file-control to 
f270: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
f280: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
f290: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
f2a0: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
f2b0: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
f2c0: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
f2d0: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
f2e0: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
f2f0: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
f300: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
f310: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
f320: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
f330: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
f340: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
f350: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
f360: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
f370: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
f380: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
f390: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
f3a0: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
f3b0: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
f3c0: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
f3d0: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
f3e0: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
f3f0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
f400: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
f410: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
f420: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
f430: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
f440: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
f450: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
f460: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
f470: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20  ROXYFILE        
f480: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
f490: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
f4a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
f4b0: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
f4c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
f4d0: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
f4e0: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
f4f0: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
f500: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
f510: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
f520: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
f530: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
f540: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
f550: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
f560: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
f570: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
f580: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
f590: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
f5a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f5b0: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
f5c0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
f5d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
f5e0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
f5f0: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
f600: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
f610: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
f620: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
f630: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
f640: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
f650: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
f660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
f670: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
f680: 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65 66           14.#def
f690: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
f6a0: 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20 20  _BUSYHANDLER    
f6b0: 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66 69          15.#defi
f6c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
f6d0: 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20 20  TEMPFILENAME    
f6e0: 20 20 20 20 20 20 20 31 36 0a 0a 2f 2a 0a 2a 2a         16../*.**
f6f0: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
f700: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
f710: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
f720: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
f730: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
f740: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
f750: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
f760: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
f770: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
f780: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
f790: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
f7a0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
f7b0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
f7c0: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
f7d0: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
f7e0: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
f7f0: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
f800: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
f810: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
f820: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
f830: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
f840: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
f850: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
f860: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
f870: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
f880: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
f890: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
f8a0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
f8b0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
f8c0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
f8d0: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
f8e0: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
f8f0: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
f900: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
f910: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
f920: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
f930: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
f940: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
f950: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
f960: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
f970: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
f980: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
f990: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
f9a0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
f9b0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
f9c0: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
f9d0: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
f9e0: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
f9f0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
fa00: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
fa10: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
fa20: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
fa30: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
fa40: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
fa50: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
fa60: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
fa70: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
fa80: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
fa90: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
faa0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
fab0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
fac0: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
fad0: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
fae0: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
faf0: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
fb00: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
fb10: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
fb20: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
fb30: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
fb40: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
fb50: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
fb60: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
fb70: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
fb80: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
fb90: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
fba0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
fbb0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
fbc0: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
fbd0: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
fbe0: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
fbf0: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
fc00: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
fc10: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
fc20: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
fc30: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
fc40: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
fc50: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
fc60: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
fc70: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
fc80: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
fc90: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
fca0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
fcb0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
fcc0: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
fcd0: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
fce0: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
fcf0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
fd00: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
fd10: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
fd20: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
fd30: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
fd40: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
fd50: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
fd60: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
fd70: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
fd80: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
fd90: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
fda0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
fdb0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
fdc0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
fdd0: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
fde0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
fdf0: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
fe00: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
fe10: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
fe20: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
fe30: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
fe40: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
fe50: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
fe60: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
fe70: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
fe80: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
fe90: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
fea0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
feb0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
fec0: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
fed0: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
fee0: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
fef0: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
ff00: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
ff10: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
ff20: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
ff30: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
ff40: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
ff50: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
ff60: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
ff70: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
ff80: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
ff90: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
ffa0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
ffb0: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
ffc0: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
ffd0: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
ffe0: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
fff0: 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68   than.** 11 alph
10000 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
10010 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
10020 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
10030 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
10040 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
10050 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
10060 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
10070 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
10080 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
10090 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
100a0 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
100b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
100c0 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
100d0 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
100e0 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
100f0 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
10100 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
10110 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
10120 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
10130 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
10140 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
10150 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
10160 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
10170 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
10180 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
10190 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
101a0 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
101b0 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
101c0 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
101d0 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
101e0 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
101f0 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
10200 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
10210 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
10220 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
10230 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
10240 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
10250 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
10260 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
10270 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
10280 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
10290 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
102a0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
102b0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
102c0 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
102d0 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
102e0 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
102f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
10300 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
10310 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
10320 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
10330 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
10340 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
10350 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
10360 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
10370 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
10380 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
10390 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
103a0 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
103b0 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
103c0 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
103d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
103e0 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
103f0 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
10400 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
10410 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
10420 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
10430 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
10440 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
10450 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
10460 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
10470 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
10480 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
10490 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
104a0 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
104b0 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
104c0 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
104d0 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
104e0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
104f0 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
10500 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
10510 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
10520 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
10530 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
10540 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
10550 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
10560 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
10570 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
10580 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
10590 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
105a0 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
105b0 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
105c0 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
105d0 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
105e0 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
105f0 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
10600 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
10610 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
10620 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
10630 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
10640 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
10650 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
10660 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
10670 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
10680 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
10690 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
106a0 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
106b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
106c0 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
106d0 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
106e0 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
106f0 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
10700 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
10710 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
10720 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
10730 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
10740 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
10750 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
10760 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
10770 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
10780 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
10790 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
107a0 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
107b0 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
107c0 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
107d0 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
107e0 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
107f0 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
10800 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
10810 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
10820 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
10830 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
10840 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
10850 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
10860 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
10870 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
10880 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
10890 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
108a0 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
108b0 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
108c0 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
108d0 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
108e0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
108f0 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
10900 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
10910 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
10920 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
10930 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
10940 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
10950 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
10960 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
10970 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
10980 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
10990 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
109a0 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
109b0 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
109c0 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
109d0 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
109e0 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
109f0 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
10a00 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
10a10 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
10a20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
10a30 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
10a40 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
10a50 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
10a60 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
10a70 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
10a80 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
10a90 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
10aa0 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
10ab0 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
10ac0 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
10ad0 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
10ae0 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
10af0 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
10b00 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
10b10 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
10b20 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
10b30 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
10b40 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
10b50 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
10b60 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
10b70 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
10b80 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
10b90 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
10ba0 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
10bb0 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
10bc0 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
10bd0 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
10be0 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
10bf0 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
10c00 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
10c10 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
10c20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
10c30 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
10c40 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
10c50 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
10c60 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
10c70 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
10c80 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
10c90 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
10ca0 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
10cb0 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
10cc0 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
10cd0 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
10ce0 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
10cf0 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
10d00 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
10d10 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
10d20 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
10d30 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
10d40 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
10d50 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
10d60 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
10d70 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
10d80 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
10d90 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
10da0 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
10db0 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
10dc0 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
10dd0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
10de0 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
10df0 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
10e00 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
10e10 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
10e20 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
10e30 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
10e40 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
10e50 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
10e60 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
10e70 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
10e80 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
10e90 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
10ea0 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
10eb0 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
10ec0 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
10ed0 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
10ee0 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
10ef0 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
10f00 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
10f10 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
10f20 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
10f30 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
10f40 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
10f50 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
10f60 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
10f70 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
10f80 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
10f90 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
10fa0 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
10fb0 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
10fc0 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
10fd0 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
10fe0 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
10ff0 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
11000 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
11010 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
11020 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
11030 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
11040 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
11050 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
11060 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
11070 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
11080 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
11090 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
110a0 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
110b0 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
110c0 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
110d0 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
110e0 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
110f0 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
11100 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
11110 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
11120 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
11130 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
11140 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
11150 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
11160 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
11170 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
11180 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
11190 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
111a0 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
111b0 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
111c0 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
111d0 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
111e0 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
111f0 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
11200 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
11210 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
11220 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
11230 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
11240 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
11250 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
11260 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
11270 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
11280 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
11290 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20  r multiplied by 
112a0 38 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75  86400000 (the nu
112b0 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
112c0 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34  onds in .** a 24
112d0 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a  -hour day).  .**
112e0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
112f0 65 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69  e the xCurrentTi
11300 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
11310 20 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72   to get the curr
11320 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20  ent.** date and 
11330 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74  time if that met
11340 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65  hod is available
11350 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73   (if iVersion is
11360 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65   2 or .** greate
11370 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69  r and the functi
11380 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
11390 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c  t NULL) and will
113a0 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f   fall back.** to
113b0 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20   xCurrentTime() 
113c0 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  if xCurrentTimeI
113d0 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69  nt64() is unavai
113e0 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lable..**.** ^Th
113f0 65 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c  e xSetSystemCall
11400 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61  (), xGetSystemCa
11410 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53  ll(), and xNestS
11420 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65  ystemCall() inte
11430 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f  rfaces.** are no
11440 74 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51  t used by the SQ
11450 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73  Lite core.  Thes
11460 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72  e optional inter
11470 66 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64  faces are provid
11480 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46  ed.** by some VF
11490 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74  Ses to facilitat
114a0 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65  e testing of the
114b0 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76   VFS code. By ov
114c0 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73  erriding .** sys
114d0 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66  tem calls with f
114e0 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69  unctions under i
114f0 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65  ts control, a te
11500 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a  st program can.*
11510 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74  * simulate fault
11520 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64  s and error cond
11530 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c  itions that woul
11540 64 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64  d otherwise be d
11550 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69  ifficult.** or i
11560 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64  mpossible to ind
11570 75 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66  uce.  The set of
11580 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68   system calls th
11590 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69  at can be overri
115a0 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66  dden.** varies f
115b0 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61  rom one VFS to a
115c0 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d  nother, and from
115d0 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20   one version of 
115e0 74 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20  the same VFS to 
115f0 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70  the.** next.  Ap
11600 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
11610 75 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66  use these interf
11620 61 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65  aces must be pre
11630 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a  pared for any.**
11640 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65   or all of these
11650 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62   interfaces to b
11660 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68  e NULL or for th
11670 65 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20  eir behavior to 
11680 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f  change.** from o
11690 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68  ne release to th
116a0 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  e next.  Applica
116b0 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61  tions must not a
116c0 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73  ttempt to access
116d0 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65  .** any of these
116e0 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20   methods if the 
116f0 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20  iVersion of the 
11700 56 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e  VFS is less than
11710 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73   3..*/.typedef s
11720 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66  truct sqlite3_vf
11730 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74  s sqlite3_vfs;.t
11740 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
11750 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
11760 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74  r)(void);.struct
11770 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20   sqlite3_vfs {. 
11780 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20   int iVersion;  
11790 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72            /* Str
117a0 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e  ucture version n
117b0 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79  umber (currently
117c0 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f   3) */.  int szO
117d0 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20  sFile;          
117e0 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62    /* Size of sub
117f0 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f  classed sqlite3_
11800 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78  file */.  int mx
11810 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20  Pathname;       
11820 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69     /* Maximum fi
11830 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67  le pathname leng
11840 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  th */.  sqlite3_
11850 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20  vfs *pNext;     
11860 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65   /* Next registe
11870 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e  red VFS */.  con
11880 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20  st char *zName; 
11890 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
118a0 20 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69   this virtual fi
118b0 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76  le system */.  v
118c0 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20  oid *pAppData;  
118d0 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74          /* Point
118e0 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f  er to applicatio
118f0 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20  n-specific data 
11900 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e  */.  int (*xOpen
11910 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
11920 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
11930 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e, sqlite3_file*
11940 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,.              
11950 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
11960 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69  *pOutFlags);.  i
11970 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71  nt (*xDelete)(sq
11980 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
11990 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
119a0 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69  nt syncDir);.  i
119b0 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71  nt (*xAccess)(sq
119c0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
119d0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69  t char *zName, i
119e0 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70  nt flags, int *p
119f0 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
11a00 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28  *xFullPathname)(
11a10 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
11a20 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
11a30 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20   int nOut, char 
11a40 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a  *zOut);.  void *
11a50 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74  (*xDlOpen)(sqlit
11a60 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
11a70 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b  har *zFilename);
11a80 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72  .  void (*xDlErr
11a90 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
11aa0 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61  , int nByte, cha
11ab0 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76  r *zErrMsg);.  v
11ac0 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28  oid (*(*xDlSym)(
11ad0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69  sqlite3_vfs*,voi
11ae0 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  d*, const char *
11af0 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b  zSymbol))(void);
11b00 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f  .  void (*xDlClo
11b10 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  se)(sqlite3_vfs*
11b20 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20  , void*);.  int 
11b30 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73  (*xRandomness)(s
11b40 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
11b50 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f   nByte, char *zO
11b60 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c  ut);.  int (*xSl
11b70 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73  eep)(sqlite3_vfs
11b80 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f  *, int microseco
11b90 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  nds);.  int (*xC
11ba0 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69  urrentTime)(sqli
11bb0 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65  te3_vfs*, double
11bc0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74  *);.  int (*xGet
11bd0 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74  LastError)(sqlit
11be0 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68  e3_vfs*, int, ch
11bf0 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a  ar *);.  /*.  **
11c00 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f   The methods abo
11c10 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f  ve are in versio
11c20 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74  n 1 of the sqlit
11c30 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a  e_vfs object.  *
11c40 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54  * definition.  T
11c50 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77  hose that follow
11c60 20 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65   are added in ve
11c70 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72  rsion 2 or later
11c80 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43  .  */.  int (*xC
11c90 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29  urrentTimeInt64)
11ca0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73  (sqlite3_vfs*, s
11cb0 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a  qlite3_int64*);.
11cc0 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
11cd0 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
11ce0 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e  in versions 1 an
11cf0 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74  d 2 of the sqlit
11d00 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
11d10 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61  ** Those below a
11d20 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  re for version 3
11d30 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20   and greater..  
11d40 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53  */.  int (*xSetS
11d50 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74  ystemCall)(sqlit
11d60 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
11d70 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
11d80 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29  te3_syscall_ptr)
11d90 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63  ;.  sqlite3_sysc
11da0 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79  all_ptr (*xGetSy
11db0 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
11dc0 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
11dd0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f  ar *zName);.  co
11de0 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78  nst char *(*xNex
11df0 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
11e00 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
11e10 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
11e20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
11e30 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
11e40 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72  n versions 1 thr
11e50 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71  ough 3 of the sq
11e60 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
11e70 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73  .  ** New fields
11e80 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
11e90 20 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69   in figure versi
11ea0 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69  ons.  The iVersi
11eb0 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69  on.  ** value wi
11ec0 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65  ll increment whe
11ed0 6e 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65  never this happe
11ee0 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  ns. .  */.};../*
11ef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
11f00 61 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63  ags for the xAcc
11f10 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a  ess VFS method.*
11f20 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
11f30 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e  er constants can
11f40 20 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20   be used as the 
11f50 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
11f60 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73  to.** the xAcces
11f70 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b  s method of an [
11f80 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
11f90 65 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72  ect.  They deter
11fa0 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e  mine.** what kin
11fb0 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73  d of permissions
11fc0 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
11fd0 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66  hod is looking f
11fe0 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  or..** With SQLI
11ff0 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
12000 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
12010 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63  thod.** simply c
12020 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
12030 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a  e file exists..*
12040 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
12050 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20  CESS_READWRITE, 
12060 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
12070 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
12080 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64  ther the named d
12090 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68  irectory is both
120a0 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
120b0 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74  itable.** (in ot
120c0 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69  her words, if fi
120d0 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64  les can be added
120e0 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72  , removed, and r
120f0 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a  enamed within.**
12100 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e   the directory).
12110 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41  .** The SQLITE_A
12120 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
12130 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72  constant is curr
12140 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20  ently used only 
12150 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f  by the.** [temp_
12160 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
12170 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20  pragma], though 
12180 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67  this could chang
12190 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a  e in a future.**
121a0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
121b0 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49  te..** With SQLI
121c0 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20  TE_ACCESS_READ, 
121d0 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
121e0 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65  od.** checks whe
121f0 74 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73  ther the file is
12200 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
12210 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
12220 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a  AD constant is.*
12230 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73  * currently unus
12240 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69  ed, though it mi
12250 67 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61  ght be used in a
12260 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20   future release 
12270 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f  of.** SQLite..*/
12280 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12290 41 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20  ACCESS_EXISTS   
122a0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
122b0 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
122c0 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62  TE 1   /* Used b
122d0 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74  y PRAGMA temp_st
122e0 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f  ore_directory */
122f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
12300 41 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20  ACCESS_READ     
12310 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a   2   /* Unused *
12320 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
12330 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65  F: Flags for the
12340 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65   xShmLock VFS me
12350 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
12360 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
12370 74 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61  ts define the va
12380 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70  rious locking op
12390 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f  erations.** allo
123a0 77 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c  wed by the xShmL
123b0 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73  ock method of [s
123c0 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
123d0 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c  s].  The.** foll
123e0 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e  owing are the on
123f0 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61  ly legal combina
12400 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74  tions of flags t
12410 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63  o the.** xShmLoc
12420 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  k method:.**.** 
12430 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  <ul>.** <li>  SQ
12440 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
12450 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
12460 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  D.** <li>  SQLIT
12470 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
12480 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
12490 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  E.** <li>  SQLIT
124a0 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53  E_SHM_UNLOCK | S
124b0 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
124c0 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
124d0 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
124e0 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
124f0 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  VE.** </ul>.**.*
12500 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67  * When unlocking
12510 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45  , the same SHARE
12520 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66  D or EXCLUSIVE f
12530 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70  lag must be supp
12540 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67  lied as.** was g
12550 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72  iven no the corr
12560 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20  esponding lock. 
12570 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d   .**.** The xShm
12580 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20  Lock method can 
12590 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65  transition betwe
125a0 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20  en unlocked and 
125b0 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74  SHARED or.** bet
125c0 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
125d0 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74  d EXCLUSIVE.  It
125e0 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69   cannot transiti
125f0 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45  on between SHARE
12600 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49  D.** and EXCLUSI
12610 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  VE..*/.#define S
12620 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b  QLITE_SHM_UNLOCK
12630 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
12640 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
12650 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
12660 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48  ne SQLITE_SHM_SH
12670 41 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65  ARED       4.#de
12680 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
12690 45 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a  EXCLUSIVE    8..
126a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
126b0 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b  Maximum xShmLock
126c0 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65   index.**.** The
126d0 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
126e0 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   on [sqlite3_io_
126f0 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65  methods] may use
12700 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
12710 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70  en 0 and this up
12720 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73  per bound as its
12730 20 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65   "offset" argume
12740 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  nt..** The SQLit
12750 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65  e core will neve
12760 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71  r attempt to acq
12770 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20  uire or release 
12780 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64  a.** lock outsid
12790 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a  e of this range.
127a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
127b0 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20  E_SHM_NLOCK     
127c0 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50     8.../*.** CAP
127d0 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a  I3REF: Initializ
127e0 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  e The SQLite Lib
127f0 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rary.**.** ^The 
12800 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12810 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69  ze() routine ini
12820 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20  tializes the.** 
12830 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
12840 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68   ^The sqlite3_sh
12850 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65  utdown() routine
12860 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20  .** deallocates 
12870 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68  any resources th
12880 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65  at were allocate
12890 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69  d by sqlite3_ini
128a0 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68  tialize()..** Th
128b0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
128c0 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64   designed to aid
128d0 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74   in process init
128e0 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a  ialization and.*
128f0 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d  * shutdown on em
12900 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20  bedded systems. 
12910 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70   Workstation app
12920 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a  lications using.
12930 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c  ** SQLite normal
12940 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ly do not need t
12950 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20  o invoke either 
12960 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
12970 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  s..**.** A call 
12980 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  to sqlite3_initi
12990 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65  alize() is an "e
129a0 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69  ffective" call i
129b0 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66  f it is.** the f
129c0 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65  irst time sqlite
129d0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
129e0 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67  s invoked during
129f0 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66   the lifetime of
12a00 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c  .** the process,
12a10 20 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65   or if it is the
12a20 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
12a30 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12a40 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66   is invoked.** f
12a50 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20  ollowing a call 
12a60 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
12a70 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61  own().  ^(Only a
12a80 6e 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c  n effective call
12a90 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69  .** of sqlite3_i
12aa0 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73  nitialize() does
12ab0 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74   any initializat
12ac0 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ion.  All other 
12ad0 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72  calls.** are har
12ae0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a  mless no-ops.)^.
12af0 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
12b00 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12b10 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
12b20 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
12b30 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20  is the first.** 
12b40 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
12b50 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65  shutdown() since
12b60 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65   the last sqlite
12b70 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20  3_initialize(). 
12b80 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66   ^(Only.** an ef
12b90 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20  fective call to 
12ba0 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12bb0 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e  () does any dein
12bc0 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  itialization..**
12bd0 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64   All other valid
12be0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
12bf0 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65  3_shutdown() are
12c00 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73   harmless no-ops
12c10 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  .)^.**.** The sq
12c20 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12c30 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
12c40 74 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20  threadsafe, but 
12c50 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12c60 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54  ().** is not.  T
12c70 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
12c80 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  own() interface 
12c90 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c  must only be cal
12ca0 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69  led from a.** si
12cb0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c  ngle thread.  Al
12cc0 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  l open [database
12cd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75   connections] mu
12ce0 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64  st be closed and
12cf0 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51   all.** other SQ
12d00 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d  Lite resources m
12d10 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  ust be deallocat
12d20 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f  ed prior to invo
12d30 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  king.** sqlite3_
12d40 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a  shutdown()..**.*
12d50 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68  * Among other th
12d60 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69  ings, ^sqlite3_i
12d70 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c  nitialize() will
12d80 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
12d90 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53  e3_os_init().  S
12da0 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74  imilarly, ^sqlit
12db0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
12dc0 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c   will invoke sql
12dd0 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a  ite3_os_end()..*
12de0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
12df0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
12e00 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b  outine returns [
12e10 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
12e20 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f  ccess..** ^If fo
12e30 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73  r some reason, s
12e40 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12e50 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  e() is unable to
12e60 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74   initialize.** t
12e70 68 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68  he library (perh
12e80 61 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65  aps it is unable
12e90 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e   to allocate a n
12ea0 65 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73  eeded resource s
12eb0 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65  uch.** as a mute
12ec0 78 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e  x) it returns an
12ed0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74   [error code] ot
12ee0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
12ef0 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  _OK]..**.** ^The
12f00 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
12f10 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ize() routine is
12f20 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c   called internal
12f30 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72  ly by many other
12f40 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
12f50 66 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e  faces so that an
12f60 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75   application usu
12f70 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65  ally does not ne
12f80 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20  ed to.** invoke 
12f90 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12fa0 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20  ze() directly.  
12fb0 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71  For example, [sq
12fc0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
12fd0 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69   calls sqlite3_i
12fe0 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74  nitialize() so t
12ff0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
13000 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  y will be automa
13010 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69  tically.** initi
13020 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c  alized when [sql
13030 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20  ite3_open()] is 
13040 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73  called if it has
13050 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69   not be initiali
13060 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20  zed.** already. 
13070 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51   ^However, if SQ
13080 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13090 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
130a0 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d  E_OMIT_AUTOINIT]
130b0 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  .** compile-time
130c0 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68   option, then th
130d0 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c  e automatic call
130e0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  s to sqlite3_ini
130f0 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65  tialize().** are
13100 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65   omitted and the
13110 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
13120 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69  t call sqlite3_i
13130 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65  nitialize() dire
13140 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f  ctly.** prior to
13150 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72   using any other
13160 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
13170 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20  e.  For maximum 
13180 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20  portability,.** 
13190 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  it is recommende
131a0 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
131b0 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b  ons always invok
131c0 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
131d0 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74  lize().** direct
131e0 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ly prior to usin
131f0 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
13200 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
13210 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a  uture releases.*
13220 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  * of SQLite may 
13230 72 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49  require this.  I
13240 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
13250 68 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69  he behavior exhi
13260 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51  bited.** when SQ
13270 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
13280 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d   with [SQLITE_OM
13290 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67  IT_AUTOINIT] mig
132a0 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a  ht become the.**
132b0 20 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f   default behavio
132c0 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65  r in some future
132d0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
132e0 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  te..**.** The sq
132f0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
13300 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65  routine does ope
13310 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70  rating-system sp
13320 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61  ecific.** initia
13330 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  lization of the 
13340 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20  SQLite library. 
13350 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f   The sqlite3_os_
13360 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  end().** routine
13370 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65   undoes the effe
13380 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73  ct of sqlite3_os
13390 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61  _init().  Typica
133a0 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f  l tasks.** perfo
133b0 72 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f  rmed by these ro
133c0 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61  utines include a
133d0 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61  llocation or dea
133e0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20  llocation.** of 
133f0 73 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73  static resources
13400 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  , initialization
13410 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61   of global varia
13420 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67  bles,.** setting
13430 20 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73   up a default [s
13440 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75  qlite3_vfs] modu
13450 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75  le, or setting u
13460 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63  p.** a default c
13470 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69  onfiguration usi
13480 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ng [sqlite3_conf
13490 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ig()]..**.** The
134a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
134b0 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  uld never invoke
134c0 20 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f   either sqlite3_
134d0 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20  os_init().** or 
134e0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
134f0 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20   directly.  The 
13500 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
13510 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a  ld only invoke.*
13520 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  * sqlite3_initia
13530 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74  lize() and sqlit
13540 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
13550 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
13560 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  nit().** interfa
13570 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74  ce is called aut
13580 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71  omatically by sq
13590 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
135a0 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  () and.** sqlite
135b0 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61  3_os_end() is ca
135c0 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  lled by sqlite3_
135d0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70  shutdown().  App
135e0 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c  ropriate.** impl
135f0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20  ementations for 
13600 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
13610 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73  ) and sqlite3_os
13620 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75  _end().** are bu
13630 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20  ilt into SQLite 
13640 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69  when it is compi
13650 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69  led for Unix, Wi
13660 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a  ndows, or OS/2..
13670 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20  ** When [custom 
13680 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66  builds | built f
13690 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72  or other platfor
136a0 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68  ms].** (using th
136b0 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48  e [SQLITE_OS_OTH
136c0 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ER=1] compile-ti
136d0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68  me.** option) th
136e0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
136f0 73 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74  st supply a suit
13700 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  able implementat
13710 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  ion for.** sqlit
13720 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
13730 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
13740 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69  ).  An applicati
13750 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69  on-supplied.** i
13760 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
13770 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
13780 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  () or sqlite3_os
13790 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72  _end().** must r
137a0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b  eturn [SQLITE_OK
137b0 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64  ] on success and
137c0 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72   some other [err
137d0 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a  or code] upon.**
137e0 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c   failure..*/.SQL
137f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
13800 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76  te3_initialize(v
13810 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
13820 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75   int sqlite3_shu
13830 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c  tdown(void);.SQL
13840 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
13850 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64  te3_os_init(void
13860 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
13870 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  t sqlite3_os_end
13880 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  (void);../*.** C
13890 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
138a0 72 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20  ring The SQLite 
138b0 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68  Library.**.** Th
138c0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
138d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
138e0 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f  used to make glo
138f0 62 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  bal configuratio
13900 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
13910 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20  SQLite in order 
13920 74 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74  to tune SQLite t
13930 6f 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e  o the specific n
13940 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61  eeds of.** the a
13950 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65  pplication.  The
13960 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
13970 72 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d  ration is recomm
13980 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a  ended for most.*
13990 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  * applications a
139a0 6e 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69  nd so this routi
139b0 6e 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f  ne is usually no
139c0 74 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74  t necessary.  It
139d0 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20   is.** provided 
139e0 74 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20  to support rare 
139f0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74  applications wit
13a00 68 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e  h unusual needs.
13a10 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
13a20 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
13a30 72 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72  rface is not thr
13a40 65 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70  eadsafe.  The ap
13a50 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73  plication.** mus
13a60 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f  t insure that no
13a70 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
13a80 74 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76  terfaces are inv
13a90 6f 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a  oked by other.**
13aa0 20 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73   threads while s
13ab0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
13ac0 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72  is running.  Fur
13ad0 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65  thermore, sqlite
13ae0 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61  3_config().** ma
13af0 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65  y only be invoke
13b00 64 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61  d prior to libra
13b10 72 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ry initializatio
13b20 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
13b30 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
13b40 5d 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64  ] or after shutd
13b50 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  own by [sqlite3_
13b60 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20  shutdown()]..** 
13b70 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ^If sqlite3_conf
13b80 69 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61  ig() is called a
13b90 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e  fter [sqlite3_in
13ba0 69 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20  itialize()] and 
13bb0 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74  before.** [sqlit
13bc0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74  e3_shutdown()] t
13bd0 68 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75  hen it will retu
13be0 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  rn SQLITE_MISUSE
13bf0 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76  ..** Note, howev
13c00 65 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65  er, that ^sqlite
13c10 33 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62  3_config() can b
13c20 65 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74  e called as part
13c30 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65   of the.** imple
13c40 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20  mentation of an 
13c50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
13c60 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f  ned [sqlite3_os_
13c70 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  init()]..**.** T
13c80 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13c90 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  t to sqlite3_con
13ca0 66 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65  fig() is an inte
13cb0 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72  ger.** [configur
13cc0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
13cd0 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
13ce0 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
13cf0 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
13d00 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
13d10 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
13d20 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
13d30 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f  nding on the [co
13d40 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
13d50 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
13d60 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a  rst argument..**
13d70 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66  .** ^When a conf
13d80 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
13d90 20 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33   is set, sqlite3
13da0 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
13db0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
13dc0 2a 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e  * ^If the option
13dd0 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53   is unknown or S
13de0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
13df0 74 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f  to set the optio
13e00 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72  n.** then this r
13e10 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
13e20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
13e30 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54   code]..*/.SQLIT
13e40 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
13e50 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e  3_config(int, ..
13e60 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
13e70 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64  REF: Configure d
13e80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13e90 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ons.**.** The sq
13ea0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
13eb0 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
13ec0 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66  sed to make conf
13ed0 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61  iguration.** cha
13ee0 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62  nges to a [datab
13ef0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
13f00 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20    The interface 
13f10 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a  is similar to.**
13f20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13f30 28 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20  ()] except that 
13f40 74 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c  the changes appl
13f50 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a  y to a single.**
13f60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13f70 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65  ction] (specifie
13f80 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  d in the first a
13f90 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20  rgument)..**.** 
13fa0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
13fb0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  ent to sqlite3_d
13fc0 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e  b_config(D,V,...
13fd0 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51  )  is the.** [SQ
13fe0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
13ff0 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67  OKASIDE | config
14000 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20  uration verb] - 
14010 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
14020 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74  .** that indicat
14030 65 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f  es what aspect o
14040 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
14050 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62  connection] is b
14060 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e  eing configured.
14070 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61  .** Subsequent a
14080 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65  rguments vary de
14090 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63  pending on the c
140a0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72  onfiguration ver
140b0 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20  b..**.** ^Calls 
140c0 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  to sqlite3_db_co
140d0 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51  nfig() return SQ
140e0 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f  LITE_OK if and o
140f0 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61  nly if.** the ca
14100 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  ll is considered
14110 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a   successful..*/.
14120 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
14130 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
14140 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
14150 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
14160 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
14170 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
14180 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
14190 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
141a0 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
141b0 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
141c0 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
141d0 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
141e0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
141f0 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
14200 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
14210 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
14220 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
14230 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
14240 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
14250 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
14260 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
14270 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
14280 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14290 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
142a0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
142b0 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
142c0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
142d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
142e0 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
142f0 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
14300 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
14310 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
14320 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
14330 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
14340 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
14350 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
14360 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
14370 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
14380 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
14390 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
143a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
143b0 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
143c0 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
143d0 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
143e0 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
143f0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
14400 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
14410 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
14420 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
14430 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
14440 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
14450 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
14460 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
14470 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
14480 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
14490 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
144a0 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
144b0 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
144c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
144d0 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
144e0 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
144f0 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
14500 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
14510 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
14520 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
14530 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
14540 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
14550 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
14560 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
14570 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
14580 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
14590 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
145a0 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
145b0 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
145c0 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
145d0 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
145e0 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
145f0 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
14600 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46  xRealloc, and xF
14610 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  ree methods must
14620 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
14630 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  * malloc(), real
14640 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
14650 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
14660 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
14670 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  ibrary..** ^SQLi
14680 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
14690 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
146a0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
146b0 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
146c0 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
146d0 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
146e0 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
146f0 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
14700 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
14710 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
14720 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
14730 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
14740 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
14750 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
14760 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
14770 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
14780 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
14790 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
147a0 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
147b0 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
147c0 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
147d0 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
147e0 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
147f0 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
14800 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
14810 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
14820 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
14830 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
14840 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
14850 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
14860 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
14870 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
14880 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
14890 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
148a0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
148b0 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
148c0 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
148d0 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
148e0 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
148f0 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
14900 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
14910 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
14920 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
14930 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
14940 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
14950 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
14960 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
14970 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
14980 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
14990 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
149a0 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
149b0 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
149c0 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
149d0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
149e0 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
149f0 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
14a00 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
14a10 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
14a20 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
14a30 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
14a40 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
14a50 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
14a60 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
14a70 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
14a80 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
14a90 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
14aa0 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
14ab0 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
14ac0 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
14ad0 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
14ae0 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
14af0 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
14b00 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
14b10 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
14b20 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
14b30 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
14b40 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
14b50 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
14b60 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
14b70 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
14b80 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
14b90 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
14ba0 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
14bb0 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
14bc0 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
14bd0 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
14be0 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
14bf0 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
14c00 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
14c10 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
14c20 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
14c30 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
14c40 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
14c50 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
14c60 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
14c70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
14c80 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
14c90 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14ca0 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
14cb0 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
14cc0 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
14cd0 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
14ce0 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
14cf0 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
14d00 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
14d10 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
14d20 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
14d30 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
14d40 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
14d50 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
14d60 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
14d70 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
14d80 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
14d90 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
14da0 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
14db0 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
14dc0 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
14dd0 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
14de0 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
14df0 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
14e00 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
14e10 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
14e20 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
14e30 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
14e40 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
14e50 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
14e60 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
14e70 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
14e80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
14e90 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
14ea0 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
14eb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
14ec0 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
14ed0 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
14ee0 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
14ef0 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
14f00 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
14f10 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
14f20 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
14f30 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
14f40 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
14f50 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
14f60 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
14f70 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
14f80 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
14f90 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
14fa0 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
14fb0 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
14fc0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
14fd0 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
14fe0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
14ff0 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
15000 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
15010 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
15020 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
15030 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
15040 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
15050 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
15060 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
15070 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
15080 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
15090 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
150a0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
150b0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
150c0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
150d0 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
150e0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
150f0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
15100 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
15110 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
15120 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
15130 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
15140 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
15150 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15160 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
15170 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
15180 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
15190 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
151a0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
151b0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
151c0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
151d0 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
151e0 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
151f0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
15200 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
15210 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
15220 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
15230 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
15240 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
15250 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
15260 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
15270 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
15280 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
15290 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
152a0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
152b0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
152c0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
152d0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
152e0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
152f0 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
15300 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
15310 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
15320 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
15330 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
15340 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
15350 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
15360 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
15370 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
15380 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
15390 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
153a0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
153b0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
153c0 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
153d0 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
153e0 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
153f0 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
15400 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
15410 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
15420 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
15430 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15440 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15450 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
15460 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
15470 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15480 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
15490 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
154a0 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
154b0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
154c0 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
154d0 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
154e0 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
154f0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
15500 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
15510 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
15520 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
15530 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
15540 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
15550 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
15560 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
15570 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15580 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
15590 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
155a0 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
155b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
155c0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
155d0 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
155e0 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
155f0 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
15600 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
15610 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
15620 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
15630 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
15640 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
15650 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
15660 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
15670 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
15680 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
15690 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
156a0 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
156b0 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
156c0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
156d0 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
156e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
156f0 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
15700 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
15710 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
15720 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
15730 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
15740 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
15750 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
15760 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
15770 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
15780 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
15790 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
157a0 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
157b0 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
157c0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
157d0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
157e0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
157f0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
15800 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
15810 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
15820 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
15830 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
15840 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
15850 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
15860 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
15870 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
15880 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
15890 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
158a0 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
158b0 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
158c0 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
158d0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
158e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
158f0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
15900 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15910 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
15920 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
15930 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
15940 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
15950 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
15960 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
15970 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
15980 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
15990 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
159a0 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
159b0 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
159c0 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
159d0 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
159e0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
159f0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
15a00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
15a10 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
15a20 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
15a30 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
15a40 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
15a50 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
15a60 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
15a70 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
15a80 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
15a90 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
15aa0 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
15ab0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15ac0 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
15ad0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
15ae0 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
15af0 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
15b00 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
15b10 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
15b20 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
15b30 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
15b40 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
15b50 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
15b60 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
15b70 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
15b80 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
15b90 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
15ba0 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
15bb0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
15bc0 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
15bd0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
15be0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
15bf0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
15c00 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
15c10 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
15c20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
15c30 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
15c40 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
15c50 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
15c60 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
15c70 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
15c80 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15c90 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
15ca0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
15cb0 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
15cc0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
15cd0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
15ce0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
15cf0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
15d00 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
15d10 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
15d20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
15d30 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
15d40 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
15d50 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
15d60 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
15d70 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
15d80 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
15d90 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
15da0 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
15db0 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
15dc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
15dd0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
15de0 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
15df0 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
15e00 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
15e10 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
15e20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
15e30 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
15e40 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
15e50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
15e60 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
15e70 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
15e80 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15e90 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
15ea0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
15eb0 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
15ec0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
15ed0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
15ee0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
15ef0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
15f00 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
15f10 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
15f20 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
15f30 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
15f40 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
15f50 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
15f60 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
15f70 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
15f80 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
15f90 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
15fa0 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
15fb0 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
15fc0 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
15fd0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
15fe0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
15ff0 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
16000 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
16010 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
16020 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
16030 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
16040 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
16050 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
16060 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
16070 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
16080 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
16090 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
160a0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
160b0 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
160c0 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
160d0 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
160e0 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
160f0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
16100 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
16110 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
16120 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
16130 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
16140 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
16150 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
16160 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
16170 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
16180 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
16190 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
161a0 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
161b0 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
161c0 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
161d0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
161e0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
161f0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
16200 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
16210 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
16220 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
16230 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
16240 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
16250 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
16260 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
16270 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
16280 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
16290 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
162a0 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
162b0 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
162c0 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
162d0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
162e0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
162f0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
16300 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
16310 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
16320 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16330 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
16340 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
16350 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
16360 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16370 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
16380 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
16390 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
163a0 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
163b0 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
163c0 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
163d0 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
163e0 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
163f0 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
16400 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
16410 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
16420 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
16430 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
16440 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
16450 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
16460 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
16470 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
16480 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
16490 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68  cations (N).  Th
164a0 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
164b0 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
164c0 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68  ple of 16..** Th
164d0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
164e0 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
164f0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
16500 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
16510 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
16520 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
16530 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
16540 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
16550 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68  than two scratch
16560 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
16570 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
16580 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
16590 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65  wice the expecte
165a0 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
165b0 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20   of threads..** 
165c0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
165d0 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72  er require a scr
165e0 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
165f0 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
16600 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
16610 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
16620 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
16630 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
16640 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
16650 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
16660 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
16670 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
16680 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
16690 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
166a0 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
166b0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
166c0 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
166d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
166e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
166f0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
16700 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
16710 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
16720 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
16730 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
16740 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
16750 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
16760 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
16770 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
16780 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
16790 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
167a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
167b0 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
167c0 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
167d0 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
167e0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
167f0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
16800 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
16810 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
16820 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
16830 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e  _PCACHE2 option.
16840 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
16850 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
16860 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
16870 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
16880 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
16890 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
168a0 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
168b0 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
168c0 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
168d0 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
168e0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
168f0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
16900 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
16910 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
16920 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
16930 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
16940 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
16950 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
16960 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
16970 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72  ^The page header
16980 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
16990 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
169a0 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
169b0 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
169c0 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
169d0 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
169e0 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
169f0 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c  * to make sz a l
16a00 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e  ittle too large.
16a10 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
16a20 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
16a30 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
16a40 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
16a50 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
16a60 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
16a70 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
16a80 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
16a90 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
16aa0 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
16ab0 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
16ac0 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
16ad0 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
16ae0 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
16af0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
16b00 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
16b10 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
16b20 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
16b30 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
16b40 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
16b50 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
16b60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
16b70 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
16b80 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
16b90 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ace..** The poin
16ba0 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
16bb0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
16bc0 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
16bd0 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
16be0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
16bf0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
16c00 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
16c10 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
16c20 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16c30 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
16c40 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
16c50 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
16c60 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
16c70 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
16c80 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
16c90 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
16ca0 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
16cb0 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
16cc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
16cd0 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
16ce0 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
16cf0 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
16d00 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
16d10 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
16d20 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
16d30 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
16d40 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
16d50 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
16d60 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
16d70 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
16d80 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
16d90 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
16da0 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
16db0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
16dc0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
16dd0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
16de0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
16df0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
16e00 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
16e10 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
16e20 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
16e30 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
16e40 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
16e50 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
16e60 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
16e70 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
16e80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
16e90 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
16ea0 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
16eb0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
16ec0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
16ed0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
16ee0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
16ef0 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
16f00 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
16f10 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
16f20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
16f30 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
16f40 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
16f50 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
16f60 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
16f70 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
16f80 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
16f90 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
16fa0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
16fb0 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
16fc0 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
16fd0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
16fe0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
16ff0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
17000 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
17010 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
17020 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
17030 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
17040 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
17050 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
17060 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
17070 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
17080 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17090 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
170a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
170b0 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
170c0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
170d0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
170e0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
170f0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
17100 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
17110 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
17120 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
17130 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
17140 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
17150 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
17160 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
17170 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
17180 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
17190 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
171a0 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
171b0 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
171c0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
171d0 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  ** content of th
171e0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
171f0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
17200 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
17210 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
17220 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
17230 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
17240 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
17250 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
17260 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
17270 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
17280 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
17290 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
172a0 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
172b0 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
172c0 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
172d0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
172e0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
172f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
17300 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
17310 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
17320 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
17330 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
17340 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
17350 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
17360 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
17370 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
17380 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
17390 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
173a0 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
173b0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
173c0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
173d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
173e0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
173f0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
17400 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
17410 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
17420 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
17430 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
17440 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
17450 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
17460 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
17470 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
17480 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
17490 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
174a0 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
174b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
174c0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
174d0 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
174e0 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
174f0 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
17500 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
17510 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
17520 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
17530 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
17540 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
17550 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
17560 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
17570 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
17580 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
17590 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
175a0 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
175b0 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
175c0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
175d0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
175e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
175f0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
17600 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
17610 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
17620 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
17630 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
17640 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
17650 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17660 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
17670 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17680 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
17690 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
176a0 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
176b0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
176c0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
176d0 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
176e0 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  location for the
176f0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
17700 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65  y allocator on e
17710 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
17720 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
17730 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
17740 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
17750 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
17760 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
17770 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
17780 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
17790 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
177a0 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
177b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
177c0 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20    ^(This option 
177d0 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64  sets the.** <i>d
177e0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
177f0 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
17800 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
17810 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
17820 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
17830 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
17840 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
17850 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
17860 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
17870 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
17880 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
17890 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
178a0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
178b0 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
178c0 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
178d0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
178e0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
178f0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
17900 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
17910 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
17920 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
17930 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
17940 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
17950 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
17960 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
17970 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
17980 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
17990 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
179a0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
179b0 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
179c0 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
179d0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
179e0 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
179f0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
17a00 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
17a10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17a20 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
17a30 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
17a40 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
17a50 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
17a60 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
17a70 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
17a80 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
17a90 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
17aa0 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
17ab0 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
17ac0 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
17ad0 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
17ae0 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
17af0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17b00 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
17b10 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
17b20 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
17b30 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
17b40 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
17b50 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
17b60 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
17b70 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
17b80 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
17b90 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
17ba0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
17bb0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
17bc0 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
17bd0 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
17be0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
17bf0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
17c00 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
17c10 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
17c20 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
17c30 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
17c40 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
17c50 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
17c60 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
17c70 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
17c80 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
17c90 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
17ca0 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
17cb0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
17cc0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
17cd0 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
17ce0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
17cf0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
17d00 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
17d10 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
17d20 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
17d30 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
17d40 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
17d50 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
17d60 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
17d70 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
17d80 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
17d90 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
17da0 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
17db0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
17dc0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
17dd0 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
17de0 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
17df0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
17e00 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
17e10 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
17e20 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
17e30 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
17e40 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
17e50 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
17e60 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
17e70 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
17e80 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
17e90 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
17ea0 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
17eb0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
17ec0 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
17ed0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
17ee0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
17ef0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
17f00 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
17f10 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
17f20 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
17f30 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
17f40 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
17f50 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
17f60 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
17f70 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
17f80 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
17f90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17fa0 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54  IG_URI.** <dd> T
17fb0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
17fc0 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
17fd0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20  nt of type int. 
17fe0 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
17ff0 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e  n.** URI handlin
18000 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
18010 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
18020 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
18030 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
18040 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c  ng.** is globall
18050 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55  y disabled. If U
18060 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
18070 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
18080 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
18090 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
180a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
180b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
180c0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
180d0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
180e0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
180f0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
18100 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
18110 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
18120 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
18130 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
18140 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
18150 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
18160 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
18170 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
18180 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69   opened. If it i
18190 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
181a0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
181b0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
181c0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
181d0 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
181e0 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
181f0 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
18200 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18210 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20  n is opened. By 
18220 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
18230 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
18240 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
18250 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
18260 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
18270 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
18280 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
18290 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
182a0 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
182b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
182c0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
182d0 43 41 4e 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  CAN]] <dt>SQLITE
182e0 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47  _CONFIG_COVERING
182f0 5f 49 4e 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c  _INDEX_SCAN.** <
18300 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  dd> This option 
18310 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 69  takes a single i
18320 6e 74 65 67 65 72 20 61 72 67 75 6d 65 6e 74 20  nteger argument 
18330 77 68 69 63 68 20 69 73 20 69 6e 74 65 72 70 72  which is interpr
18340 65 74 65 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f  eted as.** a boo
18350 6c 65 61 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f  lean in order to
18360 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
18370 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f  le the use of co
18380 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66  vering indices f
18390 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65  or.** full table
183a0 20 73 63 61 6e 73 20 69 6e 20 74 68 65 20 71 75   scans in the qu
183b0 65 72 79 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20  ery optimizer.  
183c0 54 68 65 20 64 65 66 61 75 6c 74 20 73 65 74 74  The default sett
183d0 69 6e 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65  ing is determine
183e0 64 0a 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c  d.** by the [SQL
183f0 49 54 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49  ITE_ALLOW_COVERI
18400 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63  NG_INDEX_SCAN] c
18410 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
18420 6f 6e 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a  on, or is "on".*
18430 2a 20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c  * if that compil
18440 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
18450 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65   omitted..** The
18460 20 61 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61   ability to disa
18470 62 6c 65 20 74 68 65 20 75 73 65 20 6f 66 20 63  ble the use of c
18480 6f 76 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20  overing indices 
18490 66 6f 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73  for full table s
184a0 63 61 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75  cans.** is becau
184b0 73 65 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63  se some incorrec
184c0 74 6c 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79  tly coded legacy
184d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69   applications mi
184e0 67 68 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a  ght malfunction.
184f0 2a 2a 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 20 77  ** malfunction w
18500 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  hen the optimiza
18510 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
18520 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20    Providing the 
18530 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69  ability to.** di
18540 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69  sable the optimi
18550 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68  zation allows th
18560 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61  e older, buggy a
18570 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20  pplication code 
18580 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f  to work.** witho
18590 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77  ut change even w
185a0 69 74 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f  ith newer versio
185b0 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a  ns of SQLite..**
185c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
185d0 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53  FIG_PCACHE]] [[S
185e0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
185f0 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e  PCACHE]].** <dt>
18600 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
18610 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f  ACHE and SQLITE_
18620 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
18630 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f  .** <dd> These o
18640 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c  ptions are obsol
18650 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e  ete and should n
18660 6f 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65  ot be used by ne
18670 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20  w code..** They 
18680 61 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72  are retained for
18690 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
186a0 74 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65  tibility but are
186b0 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20   now no-ops..** 
186c0 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dl>.**.** [[SQ
186d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
186e0 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  OG]].** <dt>SQLI
186f0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
18700 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74  .** <dd>This opt
18710 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
18720 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20  lable if sqlite 
18730 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
18740 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 45   the.** SQLITE_E
18750 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 20 70 72 65  NABLE_SQLLOG pre
18760 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
18770 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
18780 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
18790 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
187a0 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
187b0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
187c0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
187d0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
187e0 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
187f0 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
18800 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
18810 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
18820 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
18830 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
18840 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
18850 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
18860 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
18870 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
18880 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
18890 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
188a0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
188b0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
188c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
188d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
188e0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
188f0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
18900 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
18910 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
18920 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
18930 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
18940 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
18950 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
18960 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
18970 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
18980 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
18990 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
189a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
189b0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
189c0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
189d0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
189e0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
189f0 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
18a00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
18a10 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
18a20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
18a30 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
18a40 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
18a50 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
18a60 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
18a70 63 61 73 65 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  case..** </dl>.*
18a80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18a90 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
18aa0 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
18ab0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18ac0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
18ad0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
18ae0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18af0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
18b00 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
18b10 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
18b20 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
18b30 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
18b40 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
18b50 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
18b60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
18b70 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
18b80 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
18b90 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
18ba0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
18bb0 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
18bc0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
18bd0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
18be0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
18bf0 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
18c00 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
18c10 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
18c20 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18c30 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
18c40 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
18c50 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
18c60 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18c70 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
18c80 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
18c90 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
18ca0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
18cb0 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
18cc0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
18cd0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
18ce0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18cf0 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
18d00 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
18d10 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
18d20 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
18d30 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
18d40 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
18d50 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
18d60 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
18d70 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
18d80 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
18d90 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
18da0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
18db0 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
18dc0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
18dd0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18de0 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
18df0 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
18e00 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18e10 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
18e20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
18e30 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
18e40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
18e50 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
18e60 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
18e70 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18e80 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
18e90 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
18ea0 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
18eb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18ec0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
18ed0 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
18ee0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
18ef0 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
18f00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
18f10 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20  RING_INDEX_SCAN 
18f20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  20  /* int */.#d
18f30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18f40 46 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20  FIG_SQLLOG      
18f50 20 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c   21  /* xSqllog,
18f60 20 76 6f 69 64 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   void* */../*.**
18f70 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
18f80 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
18f90 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
18fa0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
18fb0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
18fc0 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
18fd0 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
18fe0 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
18ff0 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
19000 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
19010 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
19020 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
19030 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
19040 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
19050 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
19060 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
19070 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
19080 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
19090 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
190a0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
190b0 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
190c0 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
190d0 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
190e0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
190f0 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
19100 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
19110 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
19120 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
19130 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
19140 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
19150 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
19160 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
19170 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
19180 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
19190 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
191a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
191b0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
191c0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
191d0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
191e0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
191f0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
19200 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
19210 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
19220 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
19230 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
19240 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
19250 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
19260 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
19270 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
19280 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
19290 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
192a0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
192b0 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
192c0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
192d0 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
192e0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
192f0 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
19300 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
19310 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
19320 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
19330 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
19340 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
19350 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
19360 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
19370 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
19380 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
19390 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
193a0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
193b0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
193c0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
193d0 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
193e0 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
193f0 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
19400 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
19410 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
19420 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
19430 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
19440 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
19450 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
19460 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
19470 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
19480 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
19490 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
194a0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
194b0 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
194c0 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
194d0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
194e0 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
194f0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
19500 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
19510 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
19520 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
19530 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
19540 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
19550 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
19560 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
19570 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
19580 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
19590 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
195a0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
195b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
195c0 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
195d0 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
195e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
195f0 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
19600 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
19610 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
19620 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
19630 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
19640 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
19650 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
19660 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
19670 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
19680 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
19690 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
196a0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
196b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
196c0 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
196d0 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
196e0 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
196f0 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
19700 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
19710 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
19720 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
19730 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
19740 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
19750 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
19760 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
19770 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
19780 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
19790 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
197a0 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
197b0 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
197c0 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
197d0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
197e0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
197f0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
19800 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
19810 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
19820 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
19830 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
19840 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
19850 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
19860 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
19870 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
19880 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
19890 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
198a0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
198b0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
198c0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
198d0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
198e0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
198f0 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
19900 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
19910 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
19920 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
19930 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19940 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
19950 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
19960 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
19970 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
19980 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
19990 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
199a0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
199b0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
199c0 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
199d0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
199e0 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
199f0 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
19a00 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
19a10 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
19a20 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
19a30 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
19a40 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
19a50 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
19a60 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
19a70 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
19a80 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
19a90 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
19aa0 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
19ab0 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
19ac0 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
19ad0 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
19ae0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
19af0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
19b00 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
19b10 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
19b20 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
19b30 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
19b40 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
19b50 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
19b60 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
19b70 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
19b80 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
19b90 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
19ba0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
19bb0 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
19bc0 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
19bd0 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
19be0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
19bf0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
19c00 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
19c10 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
19c20 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
19c30 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
19c40 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
19c50 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
19c60 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
19c70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19c80 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19c90 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
19ca0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
19cb0 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
19cc0 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
19cd0 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
19ce0 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
19cf0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
19d00 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
19d10 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
19d20 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
19d30 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
19d40 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
19d50 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
19d60 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
19d70 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
19d80 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
19d90 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
19da0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
19db0 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54  bility..*/.SQLIT
19dc0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
19dd0 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
19de0 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33 2a  t_codes(sqlite3*
19df0 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f  , int onoff);../
19e00 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4c  *.** CAPI3REF: L
19e10 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69 64  ast Insert Rowid
19e20 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e 74  .**.** ^Each ent
19e30 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74 65 20  ry in an SQLite 
19e40 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e 69 71  table has a uniq
19e50 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ue 64-bit signed
19e60 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20  .** integer key 
19e70 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49  called the [ROWI
19e80 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54  D | "rowid"]. ^T
19e90 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61  he rowid is alwa
19ea0 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20  ys available.** 
19eb0 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64  as an undeclared
19ec0 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f   column named RO
19ed0 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f  WID, OID, or _RO
19ee0 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20  WID_ as long as 
19ef0 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61  those.** names a
19f00 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64  re not also used
19f10 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64   by explicitly d
19f20 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e  eclared columns.
19f30 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c   ^If.** the tabl
19f40 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f  e has a column o
19f50 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20  f type [INTEGER 
19f60 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65  PRIMARY KEY] the
19f70 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  n that column.**
19f80 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61   is another alia
19f90 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e  s for the rowid.
19fa0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
19fb0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
19fc0 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
19fd0 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73  most recent.** s
19fe0 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
19ff0 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  T] into the data
1a000 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20 5b 64  base from the [d
1a010 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a020 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69  on].** in the fi
1a030 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  rst argument.  ^
1a040 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72  As of SQLite ver
1a050 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68 69 73  sion 3.7.7, this
1a060 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72 65 63   routines.** rec
1a070 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20 69 6e  ords the last in
1a080 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20 62 6f  sert rowid of bo
1a090 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61 62 6c  th ordinary tabl
1a0a0 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61 6c 20  es and [virtual 
1a0b0 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20  tables]..** ^If 
1a0c0 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  no successful [I
1a0d0 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20  NSERT]s.** have 
1a0e0 65 76 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e  ever occurred on
1a0f0 20 74 68 61 74 20 64 61 74 61 62 61 73 65 20 63   that database c
1a100 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20  onnection, zero 
1a110 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
1a120 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45  ** ^(If an [INSE
1a130 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68 69  RT] occurs withi
1a140 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20 77  n a trigger or w
1a150 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61 6c  ithin a [virtual
1a160 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f   table].** metho
1a170 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75  d, then this rou
1a180 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  tine will return
1a190 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
1a1a0 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20  the inserted.** 
1a1b0 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  row as long as t
1a1c0 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
1a1d0 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
1a1e0 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  od is running..*
1a1f0 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20 74  * But once the t
1a200 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
1a210 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 65  l table method e
1a220 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  nds, the value r
1a230 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20 74  eturned .** by t
1a240 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76 65  his routine reve
1a250 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20 77  rts to what it w
1a260 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74 72  as before the tr
1a270 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
1a280 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  .** table method
1a290 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20   began.)^.**.** 
1a2a0 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
1a2b0 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
1a2c0 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
1a2d0 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
1a2e0 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
1a2f0 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
1a300 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
1a310 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
1a320 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
1a330 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
1a340 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
1a350 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
1a360 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
1a370 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
1a380 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
1a390 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
1a3a0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
1a3b0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
1a3c0 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
1a3d0 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
1a3e0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
1a3f0 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
1a400 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
1a410 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
1a420 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
1a430 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
1a440 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
1a450 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
1a460 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
1a470 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
1a480 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
1a490 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
1a4a0 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
1a4b0 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
1a4c0 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
1a4d0 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
1a4e0 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
1a4f0 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
1a500 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
1a510 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
1a520 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
1a530 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
1a540 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
1a550 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
1a560 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
1a570 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
1a580 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
1a590 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
1a5a0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
1a5b0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1a5c0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1a5d0 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
1a5e0 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
1a5f0 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
1a600 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a610 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
1a620 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1a630 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
1a640 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
1a650 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
1a660 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
1a670 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
1a680 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
1a690 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1a6a0 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
1a6b0 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
1a6c0 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1a6d0 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
1a6e0 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
1a6f0 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
1a700 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
1a710 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
1a720 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
1a730 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
1a740 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33  rt_rowid(sqlite3
1a750 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1a760 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e  REF: Count The N
1a770 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
1a780 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
1a790 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
1a7a0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
1a7b0 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20  f database rows 
1a7c0 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65  that were change
1a7d0 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64  d.** or inserted
1a7e0 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74   or deleted by t
1a7f0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79  he most recently
1a800 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73   completed SQL s
1a810 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74  tatement.** on t
1a820 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
1a830 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69  nection] specifi
1a840 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
1a850 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28  parameter..** ^(
1a860 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61  Only changes tha
1a870 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73  t are directly s
1a880 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1a890 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54  [INSERT], [UPDAT
1a8a0 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54  E],.** or [DELET
1a8b0 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65  E] statement are
1a8c0 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c   counted.  Auxil
1a8d0 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75  iary changes cau
1a8e0 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65  sed by.** trigge
1a8f0 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b  rs or [foreign k
1a900 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20  ey actions] are 
1a910 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55  not counted.)^ U
1a920 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  se the.** [sqlit
1a930 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1a940 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ()] function to 
1a950 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e  find the total n
1a960 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
1a970 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68  .** including ch
1a980 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
1a990 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72  triggers and for
1a9a0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
1a9b0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73  ..**.** ^Changes
1a9c0 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20   to a view that 
1a9d0 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79  are simulated by
1a9e0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
1a9f0 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20  trigger].** are 
1aa00 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e  not counted.  On
1aa10 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68  ly real table ch
1aa20 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65  anges are counte
1aa30 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f  d..**.** ^(A "ro
1aa40 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63  w change" is a c
1aa50 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c  hange to a singl
1aa60 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c  e row of a singl
1aa70 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65  e table.** cause
1aa80 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20  d by an INSERT, 
1aa90 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54  DELETE, or UPDAT
1aaa0 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f  E statement.  Ro
1aab0 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63  ws that.** are c
1aac0 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65  hanged as side e
1aad0 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41  ffects of [REPLA
1aae0 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72  CE] constraint r
1aaf0 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f  esolution,.** ro
1ab00 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72  llback, ABORT pr
1ab10 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20  ocessing, [DROP 
1ab20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e  TABLE], or by an
1ab30 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61  y other.** mecha
1ab40 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75  nisms do not cou
1ab50 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77  nt as direct row
1ab60 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a   changes.)^.**.*
1ab70 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e  * A "trigger con
1ab80 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65  text" is a scope
1ab90 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68   of execution th
1aba0 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a  at begins and.**
1abb0 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73   ends with the s
1abc0 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41  cript of a [CREA
1abd0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
1abe0 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20  gger]. .** Most 
1abf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
1ac00 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20  re.** evaluated 
1ac10 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74  outside of any t
1ac20 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73  rigger.  This is
1ac30 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22   the "top level"
1ac40 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
1ac50 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67  ext.  If a trigg
1ac60 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68  er fires from th
1ac70 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a  e top level, a.*
1ac80 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  * new trigger co
1ac90 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64  ntext is entered
1aca0 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f   for the duratio
1acb0 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a  n of that one.**
1acc0 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72   trigger.  Subtr
1acd0 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75  iggers create su
1ace0 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68  bcontexts for th
1acf0 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a  eir duration..**
1ad00 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71  .** ^Calling [sq
1ad10 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72  lite3_exec()] or
1ad20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1ad30 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f  ] recursively do
1ad40 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65  es.** not create
1ad50 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63   a new trigger c
1ad60 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ontext..**.** ^T
1ad70 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
1ad80 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
1ad90 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68  of direct row ch
1ada0 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20  anges in the.** 
1adb0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
1adc0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
1add0 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20  ELETE statement 
1ade0 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a  within the same.
1adf0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
1ae00 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c  xt..**.** ^Thus,
1ae10 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f   when called fro
1ae20 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c  m the top level,
1ae30 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72   this function r
1ae40 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75  eturns the.** nu
1ae50 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20  mber of changes 
1ae60 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
1ae70 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  nt INSERT, UPDAT
1ae80 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1ae90 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72  that also occurr
1aea0 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65  ed at the top le
1aeb0 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74  vel.  ^(Within t
1aec0 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69  he body of a tri
1aed0 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c  gger,.** the sql
1aee0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69  ite3_changes() i
1aef0 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20  nterface can be 
1af00 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74  called to find t
1af10 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1af20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
1af30 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
1af40 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55  pleted INSERT, U
1af50 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
1af60 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69  .** statement wi
1af70 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
1af80 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65   the same trigge
1af90 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  r..** However, t
1afa0 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e  he number return
1afb0 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  ed does not incl
1afc0 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63  ude changes.** c
1afd0 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67  aused by subtrig
1afe0 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65  gers since those
1aff0 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20   have their own 
1b000 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a  context.)^.**.**
1b010 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
1b020 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1b030 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
1b040 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
1b050 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
1b060 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67  , and the [chang
1b070 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
1b080 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
1b090 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
1b0a0 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
1b0b0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
1b0c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1b0d0 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63  while [sqlite3_c
1b0e0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1b0f0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1b100 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
1b110 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1b120 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1b130 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
1b140 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
1b150 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
1b160 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1b170 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
1b180 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
1b190 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
1b1a0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
1b1b0 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
1b1c0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
1b1d0 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
1b1e0 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
1b1f0 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
1b200 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
1b210 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
1b220 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
1b230 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
1b240 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
1b250 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
1b260 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
1b270 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
1b280 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
1b290 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
1b2a0 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
1b2b0 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
1b2c0 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
1b2d0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
1b2e0 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
1b2f0 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
1b300 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
1b310 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
1b320 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
1b330 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
1b340 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
1b350 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
1b360 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
1b370 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
1b380 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
1b390 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
1b3a0 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
1b3b0 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
1b3c0 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
1b3d0 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
1b3e0 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
1b3f0 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
1b400 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
1b410 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
1b420 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1b430 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
1b440 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
1b450 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
1b460 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
1b470 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
1b480 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
1b490 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
1b4a0 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
1b4b0 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
1b4c0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
1b4d0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
1b4e0 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
1b4f0 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
1b500 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
1b510 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
1b520 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
1b530 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
1b540 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
1b550 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
1b560 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
1b570 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
1b580 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
1b590 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
1b5a0 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
1b5b0 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
1b5c0 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
1b5d0 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
1b5e0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
1b5f0 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
1b600 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
1b610 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ful..*/.SQLITE_A
1b620 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
1b630 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
1b640 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1b650 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
1b660 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
1b670 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
1b680 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
1b690 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
1b6a0 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
1b6b0 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
1b6c0 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
1b6d0 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
1b6e0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
1b6f0 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
1b700 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
1b710 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
1b720 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
1b730 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
1b740 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
1b750 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
1b760 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
1b770 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
1b780 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
1b790 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
1b7a0 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
1b7b0 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
1b7c0 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
1b7d0 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
1b7e0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
1b7f0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
1b800 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
1b810 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
1b820 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
1b830 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
1b840 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
1b850 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1b860 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
1b870 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
1b880 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
1b890 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
1b8a0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
1b8b0 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1b8c0 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
1b8d0 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
1b8e0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
1b8f0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1b900 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
1b910 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
1b920 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
1b930 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
1b940 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
1b950 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
1b960 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
1b970 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
1b980 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
1b990 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
1b9a0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
1b9b0 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
1b9c0 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
1b9d0 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
1b9e0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
1b9f0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
1ba00 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
1ba10 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
1ba20 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
1ba30 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
1ba40 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
1ba50 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
1ba60 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
1ba70 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1ba80 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
1ba90 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
1baa0 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
1bab0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
1bac0 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
1bad0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1bae0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
1baf0 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
1bb00 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1bb10 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1bb20 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1bb30 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
1bb40 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
1bb50 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
1bb60 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
1bb70 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
1bb80 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
1bb90 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
1bba0 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
1bbb0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1bbc0 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
1bbd0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1bbe0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1bbf0 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
1bc00 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
1bc10 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
1bc20 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
1bc30 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
1bc40 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
1bc50 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
1bc60 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
1bc70 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
1bc80 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
1bc90 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
1bca0 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
1bcb0 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
1bcc0 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
1bcd0 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1bce0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1bcf0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1bd00 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
1bd10 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
1bd20 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1bd30 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
1bd40 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
1bd50 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
1bd60 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
1bd70 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
1bd80 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53  ely happen..*/.S
1bd90 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1bda0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1bdb0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
1bdc0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
1bdd0 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
1bde0 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
1bdf0 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
1be00 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1be10 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
1be20 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
1be30 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
1be40 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
1be50 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
1be60 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
1be70 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1be80 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
1be90 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
1bea0 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
1beb0 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
1bec0 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
1bed0 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
1bee0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1bef0 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
1bf00 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
1bf10 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
1bf20 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
1bf30 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
1bf40 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
1bf50 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
1bf60 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
1bf70 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
1bf80 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
1bf90 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
1bfa0 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
1bfb0 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
1bfc0 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
1bfd0 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
1bfe0 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
1bff0 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
1c000 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
1c010 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
1c020 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
1c030 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
1c040 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
1c050 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
1c060 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
1c070 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
1c080 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
1c090 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
1c0a0 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
1c0b0 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
1c0c0 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
1c0d0 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
1c0e0 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
1c0f0 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
1c100 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1c110 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
1c120 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
1c130 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
1c140 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
1c150 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
1c160 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
1c170 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
1c180 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
1c190 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
1c1a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
1c1b0 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
1c1c0 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
1c1d0 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
1c1e0 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
1c1f0 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
1c200 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
1c210 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
1c220 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
1c230 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
1c240 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
1c250 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
1c260 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
1c270 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
1c280 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
1c290 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1c2a0 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
1c2b0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
1c2c0 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
1c2d0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
1c2e0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
1c2f0 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
1c300 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
1c310 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
1c320 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
1c330 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
1c340 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
1c350 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
1c360 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
1c370 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1c380 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1c390 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
1c3a0 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
1c3b0 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1c3c0 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1c3d0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1c3e0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
1c3f0 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
1c400 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  der..*/.SQLITE_A
1c410 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
1c420 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68  omplete(const ch
1c430 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49 54 45  ar *sql);.SQLITE
1c440 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1c450 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73  _complete16(cons
1c460 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f  t void *sql);../
1c470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
1c480 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61  egister A Callba
1c490 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c  ck To Handle SQL
1c4a0 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a  ITE_BUSY Errors.
1c4b0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74  **.** ^This rout
1c4c0 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62  ine sets a callb
1c4d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61  ack function tha
1c4e0 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b  t might be invok
1c4f0 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61  ed whenever.** a
1c500 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64  n attempt is mad
1c510 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61  e to open a data
1c520 62 61 73 65 20 74 61 62 6c 65 20 74 68 61 74 20  base table that 
1c530 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a  another thread.*
1c540 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73  * or process has
1c550 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e   locked..**.** ^
1c560 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1c570 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68  back is NULL, th
1c580 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  en [SQLITE_BUSY]
1c590 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
1c5a0 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73  R_BLOCKED].** is
1c5b0 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
1c5c0 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
1c5d0 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
1c5e0 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
1c5f0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
1c600 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
1c610 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
1c620 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
1c630 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
1c640 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
1c650 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
1c660 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1c670 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
1c680 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
1c690 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
1c6a0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
1c6b0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
1c6c0 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
1c6d0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
1c6e0 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
1c6f0 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
1c700 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
1c710 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
1c720 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
1c730 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
1c740 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65  r this locking e
1c750 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
1c760 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  * busy callback 
1c770 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20  returns 0, then 
1c780 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74  no additional at
1c790 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20  tempts are made 
1c7a0 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65  to.** access the
1c7b0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53   database and [S
1c7c0 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
1c7d0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
1c7e0 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65  CKED] is returne
1c7f0 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  d..** ^If the ca
1c800 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
1c810 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
1c820 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
1c830 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e   is made to open
1c840 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f   the database fo
1c850 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68  r reading and th
1c860 65 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e  e cycle repeats.
1c870 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65  .**.** The prese
1c880 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61  nce of a busy ha
1c890 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67  ndler does not g
1c8a0 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74  uarantee that it
1c8b0 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64   will be invoked
1c8c0 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69  .** when there i
1c8d0 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f  s lock contentio
1c8e0 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65  n. ^If SQLite de
1c8f0 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e  termines that in
1c900 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a  voking the busy.
1c910 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64  ** handler could
1c920 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61   result in a dea
1c930 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67  dlock, it will g
1c940 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75  o ahead and retu
1c950 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  rn [SQLITE_BUSY]
1c960 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  .** or [SQLITE_I
1c970 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e  OERR_BLOCKED] in
1c980 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e  stead of invokin
1c990 67 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  g the busy handl
1c9a0 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20  er..** Consider 
1c9b0 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65  a scenario where
1c9c0 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20   one process is 
1c9d0 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c  holding a read l
1c9e0 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69  ock that.** it i
1c9f0 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d  s trying to prom
1ca00 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72 76 65  ote to a reserve
1ca10 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20  d lock and.** a 
1ca20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69  second process i
1ca30 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65  s holding a rese
1ca40 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69  rved lock that i
1ca50 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74  t is trying.** t
1ca60 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20  o promote to an 
1ca70 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20  exclusive lock. 
1ca80 20 54 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   The first proce
1ca90 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65  ss cannot procee
1caa0 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20  d.** because it 
1cab0 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
1cac0 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65  e second and the
1cad0 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1cae0 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65  cannot.** procee
1caf0 64 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20  d because it is 
1cb00 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66  blocked by the f
1cb10 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70  irst.  If both p
1cb20 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f  rocesses.** invo
1cb30 6b 65 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ke the busy hand
1cb40 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69  lers, neither wi
1cb50 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67  ll make any prog
1cb60 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65  ress.  Therefore
1cb70 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75  ,.** SQLite retu
1cb80 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  rns [SQLITE_BUSY
1cb90 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  ] for the first 
1cba0 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20  process, hoping 
1cbb0 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c  that this.** wil
1cbc0 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66 69 72  l induce the fir
1cbd0 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65  st process to re
1cbe0 6c 65 61 73 65 20 69 74 73 20 72 65 61 64 20 6c  lease its read l
1cbf0 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a  ock and allow.**
1cc00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63   the second proc
1cc10 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a  ess to proceed..
1cc20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75  **.** ^The defau
1cc30 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  lt busy callback
1cc40 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   is NULL..**.** 
1cc50 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53  ^The [SQLITE_BUS
1cc60 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76  Y] error is conv
1cc70 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45  erted to [SQLITE
1cc80 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
1cc90 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69  ** when SQLite i
1cca0 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20  s in the middle 
1ccb0 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73  of a large trans
1ccc0 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c  action where all
1ccd0 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20   the.** changes 
1cce0 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74  will not fit int
1ccf0 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20  o the in-memory 
1cd00 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77  cache.  SQLite w
1cd10 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68  ill.** already h
1cd20 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44 20 6c  old a RESERVED l
1cd30 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ock on the datab
1cd40 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74  ase file, but it
1cd50 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f   needs.** to pro
1cd60 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74  mote this lock t
1cd70 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74  o EXCLUSIVE so t
1cd80 68 61 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c  hat it can spill
1cd90 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20   cache.** pages 
1cda0 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
1cdb0 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68  e file without h
1cdc0 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e  arm to concurren
1cdd0 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e  t.** readers.  ^
1cde0 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  If it is unable 
1cdf0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c  to promote the l
1ce00 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e  ock, then the in
1ce10 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65  -memory.** cache
1ce20 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e   will be left in
1ce30 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74   an inconsistent
1ce40 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68   state and so th
1ce50 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20  e error.** code 
1ce60 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d  is promoted from
1ce70 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20   the relatively 
1ce80 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42  benign [SQLITE_B
1ce90 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d  USY] to.** the m
1cea0 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49  ore severe [SQLI
1ceb0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
1cec0 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20  ].  ^This error 
1ced0 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a  code promotion.*
1cee0 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f  * forces an auto
1cef0 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f  matic rollback o
1cf00 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20  f the changes.  
1cf10 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72  See the.** <a hr
1cf20 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b  ef="/cvstrac/wik
1cf30 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f  i?p=CorruptionFo
1cf40 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
1cf50 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e  ">.** Corruption
1cf60 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
1cf70 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65  or</a> wiki page
1cf80 20 66 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f   for a discussio
1cf90 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73  n of why.** this
1cfa0 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a   is important..*
1cfb0 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e  *.** ^(There can
1cfc0 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c   only be a singl
1cfd0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64  e busy handler d
1cfe0 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a  efined for each.
1cff0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1d000 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69  nection].  Setti
1d010 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20 68 61  ng a new busy ha
1d020 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79  ndler clears any
1d030 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73  .** previously s
1d040 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e  et handler.)^  ^
1d050 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e  Note that callin
1d060 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1d070 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69  timeout()].** wi
1d080 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63  ll also set or c
1d090 6c 65 61 72 20 74 68 65 20 62 75 73 79 20 68 61  lear the busy ha
1d0a0 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ndler..**.** The
1d0b0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73   busy callback s
1d0c0 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61  hould not take a
1d0d0 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68  ny actions which
1d0e0 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64   modify the.** d
1d0f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d100 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1d110 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1d120 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63 74 69  .  Any such acti
1d130 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e  ons.** result in
1d140 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
1d150 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75  ior..** .** A bu
1d160 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20  sy handler must 
1d170 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61  not close the da
1d180 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1d190 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65  n.** or [prepare
1d1a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
1d1b0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
1d1c0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53  sy handler..*/.S
1d1d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1d1e0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1d1f0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
1d200 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20  (*)(void*,int), 
1d210 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1d220 41 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42  API3REF: Set A B
1d230 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a  usy Timeout.**.*
1d240 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1d250 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f  sets a [sqlite3_
1d260 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62  busy_handler | b
1d270 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61  usy handler] tha
1d280 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20  t sleeps.** for 
1d290 61 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75  a specified amou
1d2a0 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20  nt of time when 
1d2b0 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65  a table is locke
1d2c0 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72  d.  ^The handler
1d2d0 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d  .** will sleep m
1d2e0 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e  ultiple times un
1d2f0 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73  til at least "ms
1d300 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1d310 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61  f sleeping.** ha
1d320 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20  ve accumulated. 
1d330 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74   ^After at least
1d340 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e   "ms" millisecon
1d350 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a  ds of sleeping,.
1d360 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72  ** the handler r
1d370 65 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63  eturns 0 which c
1d380 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73  auses [sqlite3_s
1d390 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e  tep()] to return
1d3a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  .** [SQLITE_BUSY
1d3b0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  ] or [SQLITE_IOE
1d3c0 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a  RR_BLOCKED]..**.
1d3d0 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73  ** ^Calling this
1d3e0 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e   routine with an
1d3f0 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74   argument less t
1d400 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
1d410 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66  zero.** turns of
1d420 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c  f all busy handl
1d430 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ers..**.** ^(The
1d440 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
1d450 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
1d460 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69  dler for a parti
1d470 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1d480 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
1d490 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d  ny any given mom
1d4a0 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72  ent.  If another
1d4b0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a   busy handler.**
1d4c0 20 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75   was defined  (u
1d4d0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75  sing [sqlite3_bu
1d4e0 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70  sy_handler()]) p
1d4f0 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  rior to calling.
1d500 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  ** this routine,
1d510 20 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79   that other busy
1d520 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61   handler is clea
1d530 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  red.)^.*/.SQLITE
1d540 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1d550 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 73 71  _busy_timeout(sq
1d560 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73 29 3b  lite3*, int ms);
1d570 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d580 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20 52 6f  : Convenience Ro
1d590 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e 6e 69  utines For Runni
1d5a0 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a  ng Queries.**.**
1d5b0 20 54 68 69 73 20 69 73 20 61 20 6c 65 67 61 63   This is a legac
1d5c0 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  y interface that
1d5d0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 66 6f   is preserved fo
1d5e0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
1d5f0 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20 55 73  atibility..** Us
1d600 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1d610 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63 6f 6d  ace is not recom
1d620 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65  mended..**.** De
1d630 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62 3e 72  finition: A <b>r
1d640 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62 3e 20  esult table</b> 
1d650 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61 20 73  is memory data s
1d660 74 72 75 63 74 75 72 65 20 63 72 65 61 74 65 64  tructure created
1d670 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   by the.** [sqli
1d680 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d  te3_get_table()]
1d690 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41 20 72   interface.  A r
1d6a0 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65 63 6f  esult table reco
1d6b0 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c  rds the.** compl
1d6c0 65 74 65 20 71 75 65 72 79 20 72 65 73 75 6c 74  ete query result
1d6d0 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f  s from one or mo
1d6e0 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a  re queries..**.*
1d6f0 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f 6e 63  * The table conc
1d700 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61 20 6e  eptually has a n
1d710 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20 61 6e  umber of rows an
1d720 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75 74 0a  d columns.  But.
1d730 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65 72 73  ** these numbers
1d740 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20 6f 66   are not part of
1d750 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1d760 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65 73 65  e itself.  These
1d770 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72 65 20  .** numbers are 
1d780 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72 61 74  obtained separat
1d790 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65 20 74  ely.  Let N be t
1d7a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77  he number of row
1d7b0 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20 74 68  s.** and M be th
1d7c0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
1d7d0 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73  mns..**.** A res
1d7e0 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61 6e 20  ult table is an 
1d7f0 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
1d800 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  s to zero-termin
1d810 61 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e  ated UTF-8 strin
1d820 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  gs..** There are
1d830 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65 6e 74   (N+1)*M element
1d840 73 20 69 6e 20 74 68 65 20 61 72 72 61 79 2e 20  s in the array. 
1d850 20 54 68 65 20 66 69 72 73 74 20 4d 20 70 6f 69   The first M poi
1d860 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a 20 74  nters point.** t
1d870 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  o zero-terminate
1d880 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 20  d strings that  
1d890 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61 6d 65  contain the name
1d8a0 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 73  s of the columns
1d8b0 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69 6e 69  ..** The remaini
1d8c0 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c 20 70  ng entries all p
1d8d0 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20 72 65  oint to query re
1d8e0 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76 61 6c  sults.  NULL val
1d8f0 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e  ues result.** in
1d900 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 2e 20   NULL pointers. 
1d910 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 75 65   All other value
1d920 73 20 61 72 65 20 69 6e 20 74 68 65 69 72 20 55  s are in their U
1d930 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  TF-8 zero-termin
1d940 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 72  ated.** string r
1d950 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 61 73  epresentation as
1d960 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
1d970 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
1d980 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65  t()]..**.** A re
1d990 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67 68 74  sult table might
1d9a0 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e 65 20   consist of one 
1d9b0 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 61  or more memory a
1d9c0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49  llocations..** I
1d9d0 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  t is not safe to
1d9e0 20 70 61 73 73 20 61 20 72 65 73 75 6c 74 20 74   pass a result t
1d9f0 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20 74 6f  able directly to
1da00 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1da10 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  ]..** A result t
1da20 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 64  able should be d
1da30 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69 6e 67  eallocated using
1da40 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74   [sqlite3_free_t
1da50 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  able()]..**.** ^
1da60 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f  (As an example o
1da70 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  f the result tab
1da80 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70 70 6f  le format, suppo
1da90 73 65 20 61 20 71 75 65 72 79 20 72 65 73 75 6c  se a query resul
1daa0 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c 6c 6f  t.** is as follo
1dab0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1dac0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1dad0 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20 20 20        Name      
1dae0 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20 20 20    | Age.**      
1daf0 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d    --------------
1db00 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20  ---------.**    
1db10 20 20 20 20 41 6c 69 63 65 20 20 20 20 20 20 20      Alice       
1db20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20 20 42  | 43.**        B
1db30 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32 38 0a  ob         | 28.
1db40 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64 79 20  **        Cindy 
1db50 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f        | 21.** </
1db60 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1db70 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20 61 72  >.**.** There ar
1db80 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d  e two column (M=
1db90 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20 72 6f  =2) and three ro
1dba0 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68 75 73  ws (N==3).  Thus
1dbb0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 74   the.** result t
1dbc0 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74 72 69  able has 8 entri
1dbd0 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74 68 65  es.  Suppose the
1dbe0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
1dbf0 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20 61 6e   stored.** in an
1dc00 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61 7a 52   array names azR
1dc10 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61 7a 52  esult.  Then azR
1dc20 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68 69 73  esult holds this
1dc30 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20   content:.**.** 
1dc40 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1dc50 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  >.**        azRe
1dc60 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20 22 4e  sult&#91;0] = "N
1dc70 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ame";.**        
1dc80 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31 5d 20  azResult&#91;1] 
1dc90 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20 20 20  = "Age";.**     
1dca0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1dcb0 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a 2a 2a  2] = "Alice";.**
1dcc0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1dcd0 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22 3b 0a  &#91;3] = "43";.
1dce0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1dcf0 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42 6f 62  lt&#91;4] = "Bob
1dd00 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1dd10 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d 20 22  esult&#91;5] = "
1dd20 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  28";.**        a
1dd30 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d 20 3d  zResult&#91;6] =
1dd40 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20 20 20   "Cindy";.**    
1dd50 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1dd60 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c  ;7] = "21";.** <
1dd70 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1dd80 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1dd90 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1dda0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65 76 61  e() function eva
1ddb0 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20 6d 6f  luates one or mo
1ddc0 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  re.** semicolon-
1ddd0 73 65 70 61 72 61 74 65 64 20 53 51 4c 20 73 74  separated SQL st
1dde0 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20  atements in the 
1ddf0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1de00 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e 67 20  UTF-8.** string 
1de10 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72 61 6d  of its 2nd param
1de20 65 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eter and returns
1de30 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1de40 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e 74 65  to the.** pointe
1de50 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73 20 33  r given in its 3
1de60 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
1de70 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20 61 70  .** After the ap
1de80 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69  plication has fi
1de90 6e 69 73 68 65 64 20 77 69 74 68 20 74 68 65 20  nished with the 
1dea0 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71 6c 69  result from sqli
1deb0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1dec0 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61 73 73  .** it must pass
1ded0 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
1dee0 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  e pointer to sql
1def0 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1df00 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  ) in order to.**
1df10 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1df20 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d 61 6c  ory that was mal
1df30 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73 65 20  loced.  Because 
1df40 6f 66 20 74 68 65 20 77 61 79 20 74 68 65 0a 2a  of the way the.*
1df50 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
1df60 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77 69 74  c()] happens wit
1df70 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  hin sqlite3_get_
1df80 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63 61 6c  table(), the cal
1df90 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ling.** function
1dfa0 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20 74 6f   must not try to
1dfb0 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66   call [sqlite3_f
1dfc0 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c 79 2e  ree()] directly.
1dfd0 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74    Only.** [sqlit
1dfe0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1dff0 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65 6c 65   is able to rele
1e000 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  ase the memory p
1e010 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61 66 65  roperly and safe
1e020 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ly..**.** The sq
1e030 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1e040 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 69  ) interface is i
1e050 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20 61 20  mplemented as a 
1e060 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
1e070 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1e080 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  )].  The sqlite3
1e090 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72 6f 75  _get_table() rou
1e0a0 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20 68 61  tine does not ha
1e0b0 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20  ve access.** to 
1e0c0 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  any internal dat
1e0d0 61 20 73 74 72 75 63 74 75 72 65 73 20 6f 66 20  a structures of 
1e0e0 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73 65 73  SQLite.  It uses
1e0f0 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c 69 63   only the public
1e100 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 64 65  .** interface de
1e110 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41 73 20  fined here.  As 
1e120 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c 20 65  a consequence, e
1e130 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63 75 72  rrors that occur
1e140 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61 70 70   in the.** wrapp
1e150 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69 64 65  er layer outside
1e160 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c   of the internal
1e170 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1e180 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a  ] call are not.*
1e190 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e 20 73  * reflected in s
1e1a0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
1e1b0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
1e1c0 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  ode()] or.** [sq
1e1d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e  lite3_errmsg()].
1e1e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1e1f0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1e200 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1e210 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1e220 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1e230 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1e240 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1e250 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1e260 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1e270 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1e280 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1e290 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1e2a0 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1e2b0 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1e2c0 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1e2d0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1e2e0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1e2f0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1e300 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1e310 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1e320 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1e330 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1e340 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1e350 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
1e360 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  I void sqlite3_f
1e370 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a  ree_table(char *
1e380 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a  *result);../*.**
1e390 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61   CAPI3REF: Forma
1e3a0 74 74 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e  tted String Prin
1e3b0 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ting Functions.*
1e3c0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1e3d0 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69  nes are work-ali
1e3e0 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e  kes of the "prin
1e3f0 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20  tf()" family of 
1e400 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f  functions.** fro
1e410 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43  m the standard C
1e420 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20   library..**.** 
1e430 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72  ^The sqlite3_mpr
1e440 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74  intf() and sqlit
1e450 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f  e3_vmprintf() ro
1e460 75 74 69 6e 65 73 20 77 72 69 74 65 20 74 68 65  utines write the
1e470 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e  ir.** results in
1e480 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
1e490 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
1e4a0 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54  _malloc()]..** T
1e4b0 68 65 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  he strings retur
1e4c0 6e 65 64 20 62 79 20 74 68 65 73 65 20 74 77 6f  ned by these two
1e4d0 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64   routines should
1e4e0 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20   be.** released 
1e4f0 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  by [sqlite3_free
1e500 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74  ()].  ^Both rout
1e510 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a  ines return a.**
1e520 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
1e530 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1e540 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ()] is unable to
1e550 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68   allocate enough
1e560 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  .** memory to ho
1e570 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67  ld the resulting
1e580 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e   string..**.** ^
1e590 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70  (The sqlite3_snp
1e5a0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1e5b0 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73  is similar to "s
1e5c0 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a  nprintf()" from.
1e5d0 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  ** the standard 
1e5e0 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  C library.  The 
1e5f0 72 65 73 75 6c 74 20 69 73 20 77 72 69 74 74 65  result is writte
1e600 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75  n into the.** bu
1e610 66 66 65 72 20 73 75 70 70 6c 69 65 64 20 61 73  ffer supplied as
1e620 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1e630 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65  meter whose size
1e640 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20   is given by.** 
1e650 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1e660 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74  ter. Note that t
1e670 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a  he order of the.
1e680 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70 61 72  ** first two par
1e690 61 6d 65 74 65 72 73 20 69 73 20 72 65 76 65 72  ameters is rever
1e6a0 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74  sed from snprint
1e6b0 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20  f().)^  This is 
1e6c0 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c  an.** historical
1e6d0 20 61 63 63 69 64 65 6e 74 20 74 68 61 74 20 63   accident that c
1e6e0 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77  annot be fixed w
1e6f0 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a  ithout breaking.
1e700 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
1e710 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e  patibility.  ^(N
1e720 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71  ote also that sq
1e730 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1e740 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f  .** returns a po
1e750 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62 75 66  inter to its buf
1e760 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74  fer instead of t
1e770 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
1e780 63 68 61 72 61 63 74 65 72 73 20 61 63 74 75 61  characters actua
1e790 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f  lly written into
1e7a0 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20   the buffer.)^  
1e7b0 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a  We admit that.**
1e7c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
1e7d0 68 61 72 61 63 74 65 72 73 20 77 72 69 74 74 65  haracters writte
1e7e0 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72  n would be a mor
1e7f0 65 20 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a  e useful return.
1e800 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77 65 20  ** value but we 
1e810 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  cannot change th
1e820 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
1e830 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1e840 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69  intf().** now wi
1e850 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63  thout breaking c
1e860 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a  ompatibility..**
1e870 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20  .** ^As long as 
1e880 74 68 65 20 62 75 66 66 65 72 20 73 69 7a 65 20  the buffer size 
1e890 69 73 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  is greater than 
1e8a0 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e  zero, sqlite3_sn
1e8b0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72  printf().** guar
1e8c0 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
1e8d0 62 75 66 66 65 72 20 69 73 20 61 6c 77 61 79 73  buffer is always
1e8e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1e8f0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a  .  ^The first.**
1e900 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69   parameter "n" i
1e910 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65  s the total size
1e920 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 2c 20   of the buffer, 
1e930 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20  including space 
1e940 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20  for.** the zero 
1e950 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20  terminator.  So 
1e960 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69  the longest stri
1e970 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65 20 63  ng that can be c
1e980 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69  ompletely.** wri
1e990 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31  tten will be n-1
1e9a0 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a   characters..**.
1e9b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e9c0 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74  vsnprintf() rout
1e9d0 69 6e 65 20 69 73 20 61 20 76 61 72 61 72 67 73  ine is a varargs
1e9e0 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69   version of sqli
1e9f0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a  te3_snprintf()..
1ea00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
1ea10 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65  ines all impleme
1ea20 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e  nt some addition
1ea30 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a  al formatting.**
1ea40 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72   options that ar
1ea50 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e  e useful for con
1ea60 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74  structing SQL st
1ea70 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c  atements..** All
1ea80 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20 70 72   of the usual pr
1ea90 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e  intf() formattin
1eaa0 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e  g options apply.
1eab0 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74    In addition, t
1eac0 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22  here.** is are "
1ead0 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22  %q", "%Q", and "
1eae0 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a  %z" options..**.
1eaf0 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69  ** ^(The %q opti
1eb00 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73  on works like %s
1eb10 20 69 6e 20 74 68 61 74 20 69 74 20 73 75 62 73   in that it subs
1eb20 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d 74 65  titutes a nul-te
1eb30 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
1eb40 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75  ng from the argu
1eb50 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20  ment list.  But 
1eb60 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20  %q also doubles 
1eb70 65 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61  every '\'' chara
1eb80 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64  cter..** %q is d
1eb90 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20  esigned for use 
1eba0 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20  inside a string 
1ebb0 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64  literal.)^  By d
1ebc0 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27  oubling each '\'
1ebd0 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69  '.** character i
1ebe0 74 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63  t escapes that c
1ebf0 68 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c  haracter and all
1ec00 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73  ows it to be ins
1ec10 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68  erted into.** th
1ec20 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  e string..**.** 
1ec30 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73  For example, ass
1ec40 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76  ume the string v
1ec50 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f  ariable zText co
1ec60 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66  ntains text as f
1ec70 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1ec80 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1ec90 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20  **  char *zText 
1eca0 3d 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20  = "It's a happy 
1ecb0 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  day!";.** </pre>
1ecc0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1ecd0 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20  .** One can use 
1ece0 74 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20  this text in an 
1ecf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73  SQL statement as
1ed00 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1ed10 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1ed20 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1ed30 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1ed40 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1ed50 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71  table VALUES('%q
1ed60 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20  ')", zText);.** 
1ed70 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62   sqlite3_exec(db
1ed80 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29  , zSQL, 0, 0, 0)
1ed90 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72  ;.**  sqlite3_fr
1eda0 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70  ee(zSQL);.** </p
1edb0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1edc0 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
1edd0 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72  he %q format str
1ede0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
1edf0 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20   '\'' character 
1ee00 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65  in zText.** is e
1ee10 73 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53  scaped and the S
1ee20 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20  QL generated is 
1ee30 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1ee40 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1ee50 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1ee60 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1ee70 53 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79  S('It''s a happy
1ee80 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65   day!').** </pre
1ee90 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1eea0 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72  *.** This is cor
1eeb0 72 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73  rect.  Had we us
1eec0 65 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66  ed %s instead of
1eed0 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74   %q, the generat
1eee0 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20  ed SQL.** would 
1eef0 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65  have looked like
1ef00 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   this:.**.** <bl
1ef10 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1ef20 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1ef30 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1ef40 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27  's a happy day!'
1ef50 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  );.** </pre></bl
1ef60 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1ef70 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d  This second exam
1ef80 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79  ple is an SQL sy
1ef90 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20  ntax error.  As 
1efa0 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79  a general rule y
1efb0 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77  ou should.** alw
1efc0 61 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65  ays use %q inste
1efd0 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e  ad of %s when in
1efe0 73 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74  serting text int
1eff0 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  o a string liter
1f000 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  al..**.** ^(The 
1f010 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  %Q option works 
1f020 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69  like %q except i
1f030 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67  t also adds sing
1f040 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64  le quotes around
1f050 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20  .** the outside 
1f060 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72  of the total str
1f070 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ing.  Additional
1f080 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d  ly, if the param
1f090 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61  eter in the.** a
1f0a0 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20  rgument list is 
1f0b0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
1f0c0 25 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74  %Q substitutes t
1f0d0 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28  he text "NULL" (
1f0e0 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c  without.** singl
1f0f0 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f  e quotes).)^  So
1f100 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f  , for example, o
1f110 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a  ne could say:.**
1f120 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1f130 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
1f140 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d  zSQL = sqlite3_m
1f150 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49  printf("INSERT I
1f160 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53  NTO table VALUES
1f170 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  (%Q)", zText);.*
1f180 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1f190 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1f1a0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1f1b0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1f1c0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1f1d0 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  e>.**.** The cod
1f1e0 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e  e above will ren
1f1f0 64 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51  der a correct SQ
1f200 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74  L statement in t
1f210 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61  he zSQL.** varia
1f220 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20  ble even if the 
1f230 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69  zText variable i
1f240 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1f250 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25  ..**.** ^(The "%
1f260 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  z" formatting op
1f270 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1f280 22 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68  "%s" but with th
1f290 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68  e.** addition th
1f2a0 61 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72  at after the str
1f2b0 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61  ing has been rea
1f2c0 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74  d and copied int
1f2d0 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c  o.** the result,
1f2e0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f2f0 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74  ] is called on t
1f300 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
1f310 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
1f320 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6d   char *sqlite3_m
1f330 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1f340 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  r*,...);.SQLITE_
1f350 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
1f360 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
1f370 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
1f380 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  ;.SQLITE_API cha
1f390 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  r *sqlite3_snpri
1f3a0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1f3b0 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b  nst char*, ...);
1f3c0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1f3d0 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
1f3e0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1f3f0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1f400 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
1f410 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1f420 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
1f430 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
1f440 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
1f450 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
1f460 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
1f470 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
1f480 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f490 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
1f4a0 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1f4b0 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
1f4c0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
1f4d0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
1f4e0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
1f4f0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
1f500 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
1f510 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
1f520 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1f530 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
1f540 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
1f550 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f560 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1f570 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1f580 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
1f590 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
1f5a0 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
1f5b0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
1f5c0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
1f5d0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f5e0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
1f5f0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
1f600 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
1f610 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
1f620 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
1f630 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
1f640 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
1f650 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1f660 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
1f670 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1f680 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
1f690 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1f6a0 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1f6b0 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1f6c0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1f6d0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1f6e0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1f6f0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1f700 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1f710 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1f720 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1f730 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1f740 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1f750 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1f760 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1f770 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1f780 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1f790 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1f7a0 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1f7b0 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1f7c0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1f7d0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1f7e0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1f7f0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1f800 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1f810 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1f820 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1f830 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1f840 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1f850 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1f860 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1f870 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1f880 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1f890 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1f8a0 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1f8b0 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1f8c0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1f8d0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1f8e0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1f8f0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1f900 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1f910 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1f920 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1f930 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
1f940 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1f950 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
1f960 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
1f970 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
1f980 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
1f990 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
1f9a0 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
1f9b0 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
1f9c0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
1f9d0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f9e0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
1f9f0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
1fa00 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
1fa10 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1fa20 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1fa30 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
1fa40 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1fa50 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1fa60 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1fa70 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1fa80 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
1fa90 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
1faa0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1fab0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1fac0 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
1fad0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1fae0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1faf0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
1fb00 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1fb10 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1fb20 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1fb30 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1fb40 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
1fb50 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
1fb60 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1fb70 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1fb80 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
1fb90 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1fba0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1fbb0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1fbc0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1fbd0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1fbe0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
1fbf0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
1fc00 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
1fc10 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1fc20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1fc30 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1fc40 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1fc50 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1fc60 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1fc70 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1fc80 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1fc90 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1fca0 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1fcb0 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
1fcc0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1fcd0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1fce0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1fcf0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
1fd00 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
1fd10 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
1fd20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1fd30 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1fd40 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1fd50 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
1fd60 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1fd70 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1fd80 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1fd90 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1fda0 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1fdb0 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1fdc0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1fdd0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1fde0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1fdf0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1fe00 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1fe10 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1fe20 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1fe30 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1fe40 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1fe50 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1fe60 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1fe70 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1fe80 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1fe90 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1fea0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1feb0 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1fec0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1fed0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1fee0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1fef0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1ff00 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1ff10 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1ff20 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1ff30 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1ff40 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1ff50 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1ff60 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1ff70 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1ff80 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1ff90 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1ffa0 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1ffb0 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1ffc0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1ffd0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1ffe0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1fff0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
20000 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
20010 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
20020 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
20030 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
20040 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
20050 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
20060 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
20070 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
20080 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
20090 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
200a0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
200b0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
200c0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
200d0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
200e0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
200f0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
20100 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
20110 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
20120 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
20130 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
20140 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
20150 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
20160 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
20170 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
20180 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
20190 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
201a0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
201b0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
201c0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
201d0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
201e0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
201f0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
20200 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
20210 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
20220 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
20230 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  alloc()]..*/.SQL
20240 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
20250 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74  lite3_malloc(int
20260 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
20270 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c  id *sqlite3_real
20280 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  loc(void*, int);
20290 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
202a0 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f   sqlite3_free(vo
202b0 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
202c0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
202d0 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69  locator Statisti
202e0 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  cs.**.** SQLite 
202f0 70 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74  provides these t
20300 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f  wo interfaces fo
20310 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74  r reporting on t
20320 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20  he status.** of 
20330 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  the [sqlite3_mal
20340 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  loc()], [sqlite3
20350 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73  _free()], and [s
20360 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
20370 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77  ].** routines, w
20380 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75  hich form the bu
20390 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
203a0 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
203b0 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  em..**.** ^The [
203c0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
203d0 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72  sed()] routine r
203e0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
203f0 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66  r of bytes.** of
20400 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c   memory currentl
20410 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d  y outstanding (m
20420 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20  alloced but not 
20430 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20  freed)..** ^The 
20440 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
20450 68 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75  highwater()] rou
20460 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
20470 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75   maximum.** valu
20480 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65  e of [sqlite3_me
20490 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e  mory_used()] sin
204a0 63 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  ce the high-wate
204b0 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61  r mark.** was la
204c0 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20  st reset.  ^The 
204d0 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
204e0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
204f0 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a  ry_used()] and.*
20500 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
20510 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
20520 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68  nclude any overh
20530 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20  ead.** added by 
20540 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d  SQLite in its im
20550 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
20560 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
20570 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f  )],.** but not o
20580 76 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79  verhead added by
20590 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79   the any underly
205a0 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61  ing system libra
205b0 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74  ry.** routines t
205c0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  hat [sqlite3_mal
205d0 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e  loc()] may call.
205e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f  .**.** ^The memo
205f0 72 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  ry high-water ma
20600 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74  rk is reset to t
20610 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65  he current value
20620 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   of.** [sqlite3_
20630 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69  memory_used()] i
20640 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  f and only if th
20650 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a  e parameter to.*
20660 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
20670 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69  y_highwater()] i
20680 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61  s true.  ^The va
20690 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  lue returned.** 
206a0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  by [sqlite3_memo
206b0 72 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d  ry_highwater(1)]
206c0 20 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74   is the high-wat
206d0 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72  er mark.** prior
206e0 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a   to the reset..*
206f0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
20700 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
20710 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76  e3_memory_used(v
20720 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
20730 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
20740 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
20750 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
20760 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
20770 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
20780 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
20790 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
207a0 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
207b0 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
207c0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
207d0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
207e0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
207f0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
20800 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
20810 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
20820 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
20830 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
20840 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
20850 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
20860 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
20870 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
20880 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
20890 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
208a0 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
208b0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
208c0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
208d0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
208e0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
208f0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
20900 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
20910 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
20920 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
20930 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
20940 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
20950 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e  uffer P..**.** ^
20960 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74  The first time t
20970 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 69  his routine is i
20980 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72 20 69  nvoked (either i
20990 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a  nternally or by.
209a0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
209b0 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69 73 20  on) the PRNG is 
209c0 73 65 65 64 65 64 20 75 73 69 6e 67 20 72 61 6e  seeded using ran
209d0 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64  domness obtained
209e0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78 52 61  .** from the xRa
209f0 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20  ndomness method 
20a00 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  of the default [
20a10 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
20a20 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20  ect..** ^On all 
20a30 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63  subsequent invoc
20a40 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73 65 75  ations, the pseu
20a50 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73  do-randomness is
20a60 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e   generated.** in
20a70 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74  ternally and wit
20a80 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f  hout recourse to
20a90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
20aa0 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a  s] xRandomness.*
20ab0 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c  * method..*/.SQL
20ac0 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
20ad0 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28  ite3_randomness(
20ae0 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b  int N, void *P);
20af0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20b00 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41  : Compile-Time A
20b10 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c  uthorization Cal
20b20 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
20b30 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73  is routine regis
20b40 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a  ters an authoriz
20b50 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68  er callback with
20b60 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
20b70 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
20b80 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64  ction], supplied
20b90 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
20ba0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
20bb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20bc0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61  ack is invoked a
20bd0 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  s SQL statements
20be0 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69   are being compi
20bf0 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74  led.** by [sqlit
20c00 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
20c10 20 69 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73   its variants [s
20c20 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20c30 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  2()],.** [sqlite
20c40 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 61  3_prepare16()] a
20c50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
20c60 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41  are16_v2()].  ^A
20c70 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69  t various.** poi
20c80 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65 20 63  nts during the c
20c90 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65  ompilation proce
20ca0 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20  ss, as logic is 
20cb0 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a  being created.**
20cc0 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69   to perform vari
20cd0 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  ous actions, the
20ce0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20cf0 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
20d00 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f  to.** see if tho
20d10 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61  se actions are a
20d20 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75  llowed.  ^The au
20d30 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20d40 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  k should.** retu
20d50 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74  rn [SQLITE_OK] t
20d60 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69  o allow the acti
20d70 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  on, [SQLITE_IGNO
20d80 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20  RE] to disallow 
20d90 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
20da0 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77  action but allow
20db0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
20dc0 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74  nt to continue t
20dd0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  o be.** compiled
20de0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e  , or [SQLITE_DEN
20df0 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68 65 20  Y] to cause the 
20e00 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61 74 65  entire SQL state
20e10 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65  ment to be.** re
20e20 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e 20 65  jected with an e
20e30 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61  rror.  ^If the a
20e40 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20e50 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ck returns.** an
20e60 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68  y value other th
20e70 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52  an [SQLITE_IGNOR
20e80 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  E], [SQLITE_OK],
20e90 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59   or [SQLITE_DENY
20ea0 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73  ].** then the [s
20eb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20ec0 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
20ed0 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
20ee0 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75  ggered.** the au
20ef0 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
20f00 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
20f10 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20   message..**.** 
20f20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63  When the callbac
20f30 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  k returns [SQLIT
20f40 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e  E_OK], that mean
20f50 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a  s the operation.
20f60 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69 73 20  ** requested is 
20f70 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63  ok.  ^When the c
20f80 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
20f90 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74  [SQLITE_DENY], t
20fa0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  he.** [sqlite3_p
20fb0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
20fc0 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
20fd0 74 68 61 74 20 74 72 69 67 67 65 72 65 64 20 74  that triggered t
20fe0 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
20ff0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
21000 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
21010 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74   explaining that
21020 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20 64 65  .** access is de
21030 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  nied. .**.** ^Th
21040 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
21050 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  r to the authori
21060 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
21070 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68  a copy of the th
21080 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
21090 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
210a0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
210b0 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65   interface. ^The
210c0 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
210d0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  r.** to the call
210e0 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
210f0 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20  er [SQLITE_COPY 
21100 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74  | action code] t
21110 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
21120 20 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20   the particular 
21130 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74  action to be aut
21140 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68  horized. ^The th
21150 69 72 64 20 74 68 72 6f 75 67 68 20 73 69 78 74  ird through sixt
21160 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  h parameters.** 
21170 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
21180 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  are zero-termina
21190 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
211a0 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f   contain additio
211b0 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61  nal.** details a
211c0 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20  bout the action 
211d0 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64  to be authorized
211e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
211f0 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b  action code is [
21200 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20  SQLITE_READ].** 
21210 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
21220 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
21230 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
21240 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
21250 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d  tatement] statem
21260 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74  ent is construct
21270 65 64 20 74 6f 20 73 75 62 73 74 69 74 75 74 65  ed to substitute
21280 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65  .** a NULL value
21290 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65   in place of the
212a0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
212b0 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a  at would have.**
212c0 20 62 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53   been read if [S
212d0 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65  QLITE_OK] had be
212e0 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68  en returned.  Th
212f0 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  e [SQLITE_IGNORE
21300 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20  ].** return can 
21310 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20  be used to deny 
21320 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75 73 65  an untrusted use
21330 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69  r access to indi
21340 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e  vidual.** column
21350 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a  s of a table..**
21360 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20   ^If the action 
21370 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f  code is [SQLITE_
21380 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20  DELETE] and the 
21390 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
213a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  .** [SQLITE_IGNO
213b0 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45  RE] then the [DE
213c0 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20  LETE] operation 
213d0 70 72 6f 63 65 65 64 73 20 62 75 74 20 74 68 65  proceeds but the
213e0 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70  .** [truncate op
213f0 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64  timization] is d
21400 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20  isabled and all 
21410 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
21420 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a   individually..*
21430 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a  *.** An authoriz
21440 65 72 20 69 73 20 75 73 65 64 20 77 68 65 6e 20  er is used when 
21450 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21460 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a   | preparing].**
21470 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
21480 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65  from an untruste
21490 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73  d source, to ens
214a0 75 72 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ure that the SQL
214b0 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64   statements.** d
214c0 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63  o not try to acc
214d0 65 73 73 20 64 61 74 61 20 74 68 65 79 20 61 72  ess data they ar
214e0 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f  e not allowed to
214f0 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68   see, or that th
21500 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79  ey do not.** try
21510 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69   to execute mali
21520 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73  cious statements
21530 20 74 68 61 74 20 64 61 6d 61 67 65 20 74 68 65   that damage the
21540 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a   database.  For.
21550 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  ** example, an a
21560 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61  pplication may a
21570 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65  llow a user to e
21580 6e 74 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a  nter arbitrary.*
21590 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f  * SQL queries fo
215a0 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20  r evaluation by 
215b0 61 20 64 61 74 61 62 61 73 65 2e 20 20 42 75 74  a database.  But
215c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
215d0 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e   does.** not wan
215e0 74 20 74 68 65 20 75 73 65 72 20 74 6f 20 62 65  t the user to be
215f0 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72   able to make ar
21600 62 69 74 72 61 72 79 20 63 68 61 6e 67 65 73 20  bitrary changes 
21610 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
21620 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a  se.  An authoriz
21630 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65  er could then be
21640 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68   put in place wh
21650 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d  ile the.** user-
21660 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73 20 62  entered SQL is b
21670 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  eing [sqlite3_pr
21680 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 65 64  epare | prepared
21690 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c  ] that.** disall
216a0 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67 20 65  ows everything e
216b0 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73  xcept [SELECT] s
216c0 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
216d0 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
216e0 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65  at need to proce
216f0 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72  ss SQL from untr
21700 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a  usted sources.**
21710 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73   might also cons
21720 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65  ider lowering re
21730 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73  source limits us
21740 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  ing [sqlite3_lim
21750 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d  it()].** and lim
21760 69 74 69 6e 67 20 64 61 74 61 62 61 73 65 20 73  iting database s
21770 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d  ize using the [m
21780 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b  ax_page_count] [
21790 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64  PRAGMA].** in ad
217a0 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20  dition to using 
217b0 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a  an authorizer..*
217c0 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69  *.** ^(Only a si
217d0 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ngle authorizer 
217e0 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20  can be in place 
217f0 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6f  on a database co
21800 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61  nnection.** at a
21810 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c   time.  Each cal
21820 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74  l to sqlite3_set
21830 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72  _authorizer over
21840 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65  rides the.** pre
21850 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e  vious call.)^  ^
21860 44 69 73 61 62 6c 65 20 74 68 65 20 61 75 74 68  Disable the auth
21870 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c  orizer by instal
21880 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c  ling a NULL call
21890 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74  back..** The aut
218a0 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73 61 62  horizer is disab
218b0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
218c0 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
218d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  izer callback mu
218e0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
218f0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
21900 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
21910 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
21920 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
21930 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21940 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ack..** Note tha
21950 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
21960 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
21970 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
21980 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
21990 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
219a0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
219b0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
219c0 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
219d0 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  graph..**.** ^Wh
219e0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  en [sqlite3_prep
219f0 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65  are_v2()] is use
21a00 64 20 74 6f 20 70 72 65 70 61 72 65 20 61 20 73  d to prepare a s
21a10 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a  tatement, the.**
21a20 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74   statement might
21a30 20 62 65 20 72 65 2d 70 72 65 70 61 72 65 64 20   be re-prepared 
21a40 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  during [sqlite3_
21a50 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61  step()] due to a
21a60 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e   .** schema chan
21a70 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  ge.  Hence, the 
21a80 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
21a90 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  ld ensure that t
21aa0 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75  he.** correct au
21ab0 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
21ac0 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61  k remains in pla
21ad0 63 65 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73  ce during the [s
21ae0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a  qlite3_step()]..
21af0 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74  **.** ^Note that
21b00 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21b10 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
21b20 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a  ked only during.
21b30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
21b40 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61  are()] or its va
21b50 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69  riants.  Authori
21b60 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a  zation is not.**
21b70 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e   performed durin
21b80 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c  g statement eval
21b90 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74  uation in [sqlit
21ba0 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65  e3_step()], unle
21bb0 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20  ss.** as stated 
21bc0 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73 20  in the previous 
21bd0 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74  paragraph, sqlit
21be0 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65  e3_step() invoke
21bf0 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65  s.** sqlite3_pre
21c00 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70  pare_v2() to rep
21c10 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d 65  repare a stateme
21c20 6e 74 20 61 66 74 65 72 20 61 20 73 63 68 65 6d  nt after a schem
21c30 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c  a change..*/.SQL
21c40 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
21c50 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21c60 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
21c70 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
21c80 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
21c90 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
21ca0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
21cb0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
21cc0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
21cd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
21ce0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
21cf0 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
21d00 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
21d10 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
21d20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
21d30 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
21d40 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
21d50 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
21d60 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
21d70 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
21d80 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
21d90 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
21da0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
21db0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
21dc0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
21dd0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21de0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
21df0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
21e00 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
21e10 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
21e20 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
21e30 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
21e40 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
21e50 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20  SQLITE_ROLLBACK 
21e60 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a  | return code].*
21e70 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  * from the [sqli
21e80 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
21e90 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
21ea0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
21eb0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
21ec0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
21ed0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
21ee0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
21ef0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
21f00 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
21f10 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
21f20 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
21f30 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
21f40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
21f50 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
21f60 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
21f70 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21f80 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
21f90 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
21fa0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
21fb0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
21fc0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
21fd0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
21fe0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
21ff0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
22000 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
22010 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
22020 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
22030 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
22040 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
22050 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
22060 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
22070 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
22080 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
22090 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
220a0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
220b0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
220c0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
220d0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
220e0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
220f0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
22100 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
22110 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
22120 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
22130 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
22140 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
22150 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
22160 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
22170 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
22180 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
22190 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
221a0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
221b0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
221c0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
221d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
221e0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
221f0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
22200 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
22210 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
22220 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
22230 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
22240 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
22250 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
22260 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
22270 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
22280 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
22290 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
222a0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
222b0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
222c0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
222d0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
222e0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
222f0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
22300 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
22310 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22320 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
22330 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
22340 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
22350 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22360 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
22370 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
22380 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
22390 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
223a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
223b0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
223c0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
223d0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
223e0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
223f0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
22400 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
22410 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
22420 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
22430 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22440 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
22450 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
22460 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
22470 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
22480 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22490 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
224a0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
224b0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
224c0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
224d0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
224e0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
224f0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
22500 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
22510 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
22520 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22530 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
22540 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
22550 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
22560 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
22570 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
22580 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22590 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
225a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
225b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
225c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
225d0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
225e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
225f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22600 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22610 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22620 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
22630 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
22640 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
22650 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
22660 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22670 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
22680 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
22690 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
226a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
226b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
226c0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
226d0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
226e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
226f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22700 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22710 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
22720 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
22730 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22740 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22750 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22760 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
22770 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
22780 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
22790 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
227a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
227b0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
227c0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
227d0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
227e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
227f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22800 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
22810 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
22820 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
22830 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
22840 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22850 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
22860 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
22870 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
22880 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22890 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
228a0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
228b0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
228c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
228d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
228e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
228f0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
22900 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
22910 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
22920 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
22930 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
22940 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
22950 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
22960 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
22970 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
22980 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
22990 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
229a0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
229b0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
229c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
229d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
229e0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
229f0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
22a00 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
22a10 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22a20 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
22a30 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
22a40 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
22a50 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
22a60 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
22a70 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
22a80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
22a90 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
22aa0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
22ab0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22ac0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
22ad0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
22ae0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
22af0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
22b00 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22b10 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
22b20 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
22b30 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
22b40 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
22b50 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22b60 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
22b70 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
22b80 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
22b90 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22ba0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22bb0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
22bc0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
22bd0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22be0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
22bf0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22c00 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
22c10 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
22c20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
22c30 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
22c40 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22c50 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
22c60 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
22c70 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22c80 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
22c90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22ca0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
22cb0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
22cc0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
22cd0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
22ce0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22cf0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
22d00 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
22d10 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
22d20 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
22d30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22d40 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
22d50 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
22d60 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a  longer used */..
22d70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
22d80 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66  Tracing And Prof
22d90 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a  iling Functions.
22da0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
22db0 69 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61  ines register ca
22dc0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73  llback functions
22dd0 20 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65   that can be use
22de0 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67  d for.** tracing
22df0 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74   and profiling t
22e00 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20  he execution of 
22e10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
22e20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62  **.** ^The callb
22e30 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67  ack function reg
22e40 69 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74  istered by sqlit
22e50 65 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e  e3_trace() is in
22e60 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69  voked at.** vari
22e70 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61  ous times when a
22e80 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
22e90 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20  is being run by 
22ea0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
22eb0 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
22ec0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
22ed0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69  ck is invoked wi
22ee0 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65  th a UTF-8 rende
22ef0 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53  ring of the.** S
22f00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
22f10 74 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65  t as the stateme
22f20 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20  nt first begins 
22f30 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28  executing..** ^(
22f40 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74  Additional sqlit
22f50 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62  e3_trace() callb
22f60 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72  acks might occur
22f70 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67  .** as each trig
22f80 67 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d  gered subprogram
22f90 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68   is entered.  Th
22fa0 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20  e callbacks for 
22fb0 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74  triggers.** cont
22fc0 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20  ain a UTF-8 SQL 
22fd0 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65  comment that ide
22fe0 6e 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67  ntifies the trig
22ff0 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ger.)^.**.** ^Th
23000 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
23010 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
23020 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  y sqlite3_profil
23030 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
23040 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20 73 74  * as each SQL st
23050 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68 65 73  atement finishes
23060 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
23070 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e  callback contain
23080 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 61  s.** the origina
23090 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  l statement text
230a0 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61 74 65   and an estimate
230b0 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74   of wall-clock t
230c0 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f  ime.** of how lo
230d0 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e  ng that statemen
230e0 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20  t took to run.  
230f0 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
23100 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73  lback.** time is
23110 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e   in units of nan
23120 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65  oseconds, howeve
23130 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d  r the current im
23140 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20  plementation.** 
23150 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20  is only capable 
23160 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72  of millisecond r
23170 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65  esolution so the
23180 20 73 69 78 20 6c 65 61 73 74 20 73 69 67 6e 69   six least signi
23190 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73  ficant.** digits
231a0 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61 72 65   in the time are
231b0 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46   meaningless.  F
231c0 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
231d0 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68  f SQLite.** migh
231e0 74 20 70 72 6f 76 69 64 65 20 67 72 65 61 74 65  t provide greate
231f0 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20  r resolution on 
23200 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63 61 6c  the profiler cal
23210 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73  lback.  The.** s
23220 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
23230 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e   function is con
23240 73 69 64 65 72 65 64 20 65 78 70 65 72 69 6d 65  sidered experime
23250 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73  ntal and is.** s
23260 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65  ubject to change
23270 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
23280 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
23290 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
232a0 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
232b0 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
232c0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
232d0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
232e0 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  d*);.SQLITE_API 
232f0 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
23300 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
23310 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
23320 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
23330 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
23340 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
23350 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
23360 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
23370 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
23380 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
23390 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
233a0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
233b0 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
233c0 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
233d0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
233e0 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
233f0 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
23400 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
23410 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
23420 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
23430 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
23440 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
23450 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
23460 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
23470 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
23480 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
23490 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
234a0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
234b0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
234c0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
234d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
234e0 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
234f0 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
23500 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
23510 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
23520 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
23530 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
23540 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
23550 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d  f .** [virtual m
23560 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69  achine instructi
23570 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65 76  ons] that are ev
23580 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e 20  aluated between 
23590 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e  successive.** in
235a0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
235b0 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a   callback X..**.
235c0 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
235d0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
235e0 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
235f0 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
23600 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
23610 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
23620 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
23630 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
23640 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
23650 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
23660 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
23670 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
23680 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
23690 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
236a0 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
236b0 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
236c0 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
236d0 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
236e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
236f0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
23700 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
23710 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
23720 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
23730 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
23740 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
23750 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
23760 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
23770 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
23780 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
23790 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
237a0 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
237b0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
237c0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
237d0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
237e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
237f0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
23800 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
23810 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
23820 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
23830 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
23840 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23850 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
23860 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
23870 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
23880 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
23890 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
238a0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53  ragraph..**.*/.S
238b0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
238c0 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
238d0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
238e0 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28 76 6f  , int, int(*)(vo
238f0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  id*), void*);../
23900 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
23910 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44 61 74  pening A New Dat
23920 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
23930 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
23940 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e 20 53  utines open an S
23950 51 4c 69 74 65 20 64 61 74 61 62 61 73 65 20 66  QLite database f
23960 69 6c 65 20 61 73 20 73 70 65 63 69 66 69 65 64  ile as specified
23970 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69 6c 65   by the .** file
23980 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e 20 5e  name argument. ^
23990 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  The filename arg
239a0 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72 70 72  ument is interpr
239b0 65 74 65 64 20 61 73 20 55 54 46 2d 38 20 66 6f  eted as UTF-8 fo
239c0 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  r.** sqlite3_ope
239d0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
239e0 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20 61 73  open_v2() and as
239f0 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e   UTF-16 in the n
23a00 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20 6f 72  ative byte.** or
23a10 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f  der for sqlite3_
23a20 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20 5b 64  open16(). ^(A [d
23a30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23a40 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20 75 73  on] handle is us
23a50 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72 6e 65  ually.** returne
23a60 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76 65 6e  d in *ppDb, even
23a70 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63   if an error occ
23a80 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 65  urs.  The only e
23a90 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68 61 74  xception is that
23aa0 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73  .** if SQLite is
23ab0 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63   unable to alloc
23ac0 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f  ate memory to ho
23ad0 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  ld the [sqlite3]
23ae0 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20 4e 55   object,.** a NU
23af0 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69 74 74  LL will be writt
23b00 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20 69 6e  en into *ppDb in
23b10 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69 6e 74  stead of a point
23b20 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
23b30 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e  e3].** object.)^
23b40 20 5e 28 49 66 20 74 68 65 20 64 61 74 61 62 61   ^(If the databa
23b50 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28 61 6e  se is opened (an
23b60 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20 73 75  d/or created) su
23b70 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68 65 6e  ccessfully, then
23b80 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  .** [SQLITE_OK] 
23b90 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 4f 74  is returned.  Ot
23ba0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
23bb0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
23bc0 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b  ned.)^ ^The.** [
23bd0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
23be0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 65 72  ] or [sqlite3_er
23bf0 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74 69 6e  rmsg16()] routin
23c00 65 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  es can be used t
23c10 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e 20 45  o obtain.** an E
23c20 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67 65 20  nglish language 
23c30 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66 20 74  description of t
23c40 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f 77 69  he error followi
23c50 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f 66 20  ng a failure of 
23c60 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71  any.** of the sq
23c70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72 6f 75  lite3_open() rou
23c80 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tines..**.** ^Th
23c90 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f 64 69  e default encodi
23ca0 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  ng for the datab
23cb0 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54 46 2d  ase will be UTF-
23cc0 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  8 if.** sqlite3_
23cd0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
23ce0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 63  3_open_v2() is c
23cf0 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55 54 46  alled and.** UTF
23d00 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
23d10 65 20 62 79 74 65 20 6f 72 64 65 72 20 69 66 20  e byte order if 
23d20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
23d30 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
23d40 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 61  Whether or not a
23d50 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77  n error occurs w
23d60 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e 65 64  hen it is opened
23d70 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a 20 61  , resources.** a
23d80 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
23d90 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
23da0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
23db0 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65 61 73  should be releas
23dc0 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69 6e 67  ed by.** passing
23dd0 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f   it to [sqlite3_
23de0 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20 69 74  close()] when it
23df0 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 72 65   is no longer re
23e00 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  quired..**.** Th
23e10 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  e sqlite3_open_v
23e20 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 77 6f  2() interface wo
23e30 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33  rks like sqlite3
23e40 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63 65 70  _open().** excep
23e50 74 20 74 68 61 74 20 69 74 20 61 63 63 65 70 74  t that it accept
23e60 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  s two additional
23e70 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f 72 20   parameters for 
23e80 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e 74 72  additional contr
23e90 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6e  ol.** over the n
23ea0 65 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ew database conn
23eb0 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65 20 66  ection.  ^(The f
23ec0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
23ed0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65  o.** sqlite3_ope
23ee0 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b 65 20  n_v2() can take 
23ef0 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20 66 6f  one of.** the fo
23f00 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20 76 61  llowing three va
23f10 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79  lues, optionally
23f20 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 74   combined with t
23f30 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
23f40 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53  PEN_NOMUTEX], [S
23f50 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
23f60 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f  UTEX], [SQLITE_O
23f70 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
23f80 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ,.** [SQLITE_OPE
23f90 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 2c  N_PRIVATECACHE],
23fa0 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f   and/or [SQLITE_
23fb0 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 73 3a  OPEN_URI] flags:
23fc0 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  )^.**.** <dl>.**
23fd0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
23fe0 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64  PEN_READONLY]</d
23ff0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61  t>.** <dd>The da
24000 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24010 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f   in read-only mo
24020 64 65 2e 20 20 49 66 20 74 68 65 20 64 61 74 61  de.  If the data
24030 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  base does not.**
24040 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
24050 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  an error is retu
24060 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  rned.</dd>)^.**.
24070 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
24080 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d  _OPEN_READWRITE]
24090 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
240a0 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
240b0 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20  ned for reading 
240c0 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66 20 70  and writing if p
240d0 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65 61 64  ossible, or read
240e0 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66 20 74  ing.** only if t
240f0 68 65 20 66 69 6c 65 20 69 73 20 77 72 69 74 65  he file is write
24100 20 70 72 6f 74 65 63 74 65 64 20 62 79 20 74 68   protected by th
24110 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
24120 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72 0a 2a  em.  In either.*
24130 2a 20 63 61 73 65 20 74 68 65 20 64 61 74 61 62  * case the datab
24140 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61 64 79  ase must already
24150 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77 69 73   exist, otherwis
24160 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  e an error is re
24170 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
24180 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
24190 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
241a0 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45  E] | [SQLITE_OPE
241b0 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a  N_CREATE]</dt>.*
241c0 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
241d0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
241e0 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69   reading and wri
241f0 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63 72 65  ting, and is cre
24200 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20 64 6f  ated if.** it do
24210 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79 20 65  es not already e
24220 78 69 73 74 2e 20 54 68 69 73 20 69 73 20 74 68  xist. This is th
24230 65 20 62 65 68 61 76 69 6f 72 20 74 68 61 74 20  e behavior that 
24240 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 66  is always used f
24250 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  or.** sqlite3_op
24260 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  en() and sqlite3
24270 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64 3e 29  _open16().</dd>)
24280 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a  ^.** </dl>.**.**
24290 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
242a0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
242b0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 6e 6f  _open_v2() is no
242c0 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20  t one of the.** 
242d0 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73 68 6f  combinations sho
242e0 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f 6e 61  wn above optiona
242f0 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
24300 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51 4c 49  h other.** [SQLI
24310 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59  TE_OPEN_READONLY
24320 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a   | SQLITE_OPEN_*
24330 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e 20 74   bits].** then t
24340 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
24350 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
24360 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
24370 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c  OPEN_NOMUTEX] fl
24380 61 67 20 69 73 20 73 65 74 2c 20 74 68 65 6e 20  ag is set, then 
24390 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
243a0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73  nection.** opens
243b0 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d 74 68   in the multi-th
243c0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
243d0 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20 61 73  mode] as long as
243e0 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68 72 65   the single-thre
243f0 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73 20 6e  ad.** mode has n
24400 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74 20 63  ot been set at c
24410 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
24420 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49 66 20  tart-time.  ^If 
24430 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  the.** [SQLITE_O
24440 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 20 66  PEN_FULLMUTEX] f
24450 6c 61 67 20 69 73 20 73 65 74 20 74 68 65 6e 20  lag is set then 
24460 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
24470 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a  nection opens.**
24480 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a   in the serializ
24490 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
244a0 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e 67 6c  de] unless singl
244b0 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a 2a 20  e-thread was.** 
244c0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c 65 63  previously selec
244d0 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  ted at compile-t
244e0 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
244f0 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  e..** ^The [SQLI
24500 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
24510 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
24520 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
24530 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  nnection to be.*
24540 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20 75 73  * eligible to us
24550 65 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  e [shared cache 
24560 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c 65 73  mode], regardles
24570 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
24580 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  not shared.** ca
24590 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64 20 75  che is enabled u
245a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 6e  sing [sqlite3_en
245b0 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61 63 68  able_shared_cach
245c0 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b  e()].  ^The.** [
245d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56  SQLITE_OPEN_PRIV
245e0 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67 20 63  ATECACHE] flag c
245f0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
24600 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
24610 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63 69 70   not.** particip
24620 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64 20 63  ate in [shared c
24630 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65 6e 20  ache mode] even 
24640 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c 65 64  if it is enabled
24650 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
24660 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
24670 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24680 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  () is the name o
24690 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  f the.** [sqlite
246a0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 74 68  3_vfs] object th
246b0 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6f  at defines the o
246c0 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20  perating system 
246d0 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 0a 2a  interface that.*
246e0 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61  * the new databa
246f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68  se connection sh
24700 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66 20 74  ould use.  ^If t
24710 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
24720 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c  ter is.** a NULL
24730 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 74 68   pointer then th
24740 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
24750 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20 69  e3_vfs] object i
24760 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s used..**.** ^I
24770 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
24780 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20 74 68  s ":memory:", th
24790 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
247a0 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d 6f 72  mporary in-memor
247b0 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73  y database.** is
247c0 20 63 72 65 61 74 65 64 20 66 6f 72 20 74 68 65   created for the
247d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 54   connection.  ^T
247e0 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  his in-memory da
247f0 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61 6e 69  tabase will vani
24800 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 64  sh when.** the d
24810 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24820 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 46  on is closed.  F
24830 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
24840 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 0a 2a  f SQLite might.*
24850 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20 61 64  * make use of ad
24860 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69 61 6c  ditional special
24870 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61 74 20   filenames that 
24880 62 65 67 69 6e 20 77 69 74 68 20 74 68 65 20 22  begin with the "
24890 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  :" character..**
248a0 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   It is recommend
248b0 65 64 20 74 68 61 74 20 77 68 65 6e 20 61 20 64  ed that when a d
248c0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
248d0 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73 20 62   actually does b
248e0 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61 20 22  egin with.** a "
248f0 3a 22 20 63 68 61 72 61 63 74 65 72 20 79 6f 75  :" character you
24900 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78 20 74   should prefix t
24910 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69 74 68  he filename with
24920 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75 63 68   a pathname such
24930 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f 20 61   as.** "./" to a
24940 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79 2e 0a  void ambiguity..
24950 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
24960 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65 6d 70  lename is an emp
24970 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20  ty string, then 
24980 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f  a private, tempo
24990 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20  rary.** on-disk 
249a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
249b0 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68 69 73   created.  ^This
249c0 20 70 72 69 76 61 74 65 20 64 61 74 61 62 61 73   private databas
249d0 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61 75 74  e will be.** aut
249e0 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74  omatically delet
249f0 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68  ed as soon as th
24a00 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
24a10 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
24a20 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66 69 6c  .**.** [[URI fil
24a30 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69 74 65  enames in sqlite
24a40 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33 3e 55  3_open()]] <h3>U
24a50 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f 68 33  RI Filenames</h3
24a60 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55 52 49  >.**.** ^If [URI
24a70 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74 65 72   filename] inter
24a80 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61  pretation is ena
24a90 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20 66 69  bled, and the fi
24aa0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a  lename argument.
24ab0 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68 20 22  ** begins with "
24ac0 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74 68 65  file:", then the
24ad0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69 6e 74   filename is int
24ae0 65 72 70 72 65 74 65 64 20 61 73 20 61 20 55 52  erpreted as a UR
24af0 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c 65 6e  I. ^URI.** filen
24b00 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69  ame interpretati
24b10 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20 69 66  on is enabled if
24b20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
24b30 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 0a 2a  N_URI] flag is.*
24b40 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66 6f 75  * set in the fou
24b50 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rth argument to 
24b60 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24b70 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61 73 0a  ), or if it has.
24b80 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65 64 20  ** been enabled 
24b90 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67 20 74  globally using t
24ba0 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  he [SQLITE_CONFI
24bb0 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20 77 69  G_URI] option wi
24bc0 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  th the.** [sqlit
24bd0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d 65 74  e3_config()] met
24be0 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20 5b 53  hod or by the [S
24bf0 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 63  QLITE_USE_URI] c
24c00 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
24c10 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53 51 4c  on..** As of SQL
24c20 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
24c30 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20  7, URI filename 
24c40 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
24c50 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a 2a 20  s turned off.** 
24c60 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20  by default, but 
24c70 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
24c80 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
24c90 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c 65 6e  enable URI filen
24ca0 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74  ame.** interpret
24cb0 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75 6c 74  ation by default
24cc0 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66 69 6c  .  See "[URI fil
24cd0 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61 64 64  enames]" for add
24ce0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
24cf0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52  mation..**.** UR
24d00 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 20  I filenames are 
24d10 70 61 72 73 65 64 20 61 63 63 6f 72 64 69 6e 67  parsed according
24d20 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20 5e 49   to RFC 3986. ^I
24d30 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74 61 69  f the URI contai
24d40 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f 72 69  ns an.** authori
24d50 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74  ty, then it must
24d60 20 62 65 20 65 69 74 68 65 72 20 61 6e 20 65 6d   be either an em
24d70 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 74 68  pty string or th
24d80 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f  e string .** "lo
24d90 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20 74 68  calhost". ^If th
24da0 65 20 61 75 74 68 6f 72 69 74 79 20 69 73 20 6e  e authority is n
24db0 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  ot an empty stri
24dc0 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f 73 74  ng or "localhost
24dd0 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f 72 20  ", an .** error 
24de0 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f 20 74  is returned to t
24df0 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68 65 20  he caller. ^The 
24e00 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65  fragment compone
24e10 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69 66 20  nt of a URI, if 
24e20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69 73 20  .** present, is 
24e30 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
24e40 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
24e50 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  path component o
24e60 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68 65  f the URI as the
24e70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 69 73   name of the dis
24e80 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63 68 20  k file.** which 
24e90 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64 61 74  contains the dat
24ea0 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65 20 70  abase. ^If the p
24eb0 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68 20  ath begins with 
24ec0 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72 2c  a '/' character,
24ed0 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20   .** then it is 
24ee0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
24ef0 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
24f00 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 64 6f   ^If the path do
24f10 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a 2a 2a  es not begin .**
24f20 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d 65 61   with a '/' (mea
24f30 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20 61 75  ning that the au
24f40 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f 6e 20  thority section 
24f50 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
24f60 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68 65 6e  the URI).** then
24f70 20 74 68 65 20 70 61 74 68 20 69 73 20 69 6e 74   the path is int
24f80 65 72 70 72 65 74 65 64 20 61 73 20 61 20 72 65  erpreted as a re
24f90 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a 2a 2a  lative path. .**
24fa0 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20 74 68   ^On windows, th
24fb0 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e 65 6e  e first componen
24fc0 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75 74 65  t of an absolute
24fd0 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61 20 64   path .** is a d
24fe0 72 69 76 65 20 73 70 65 63 69 66 69 63 61 74 69  rive specificati
24ff0 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29 2e 0a  on (e.g. "C:")..
25000 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55 52 49  **.** [[core URI
25010 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
25020 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65 72 79  s]].** The query
25030 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
25040 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  URI may contain 
25050 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
25060 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 0a  are interpreted.
25070 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53 51 4c  ** either by SQL
25080 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72 20 62  ite itself, or b
25090 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73 74 6f  y a [VFS | custo
250a0 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  m VFS implementa
250b0 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65  tion]..** SQLite
250c0 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
250d0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
250e0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 73  query parameters
250f0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
25100 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c 2f 62    <li> <b>vfs</b
25110 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20 70 61  >: ^The "vfs" pa
25120 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 75  rameter may be u
25130 73 65 64 20 74 6f 20 73 70 65 63 69 66 79 20 74  sed to specify t
25140 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20 20 20  he name of.**   
25150 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74 20 74    a VFS object t
25160 68 61 74 20 70 72 6f 76 69 64 65 73 20 74 68 65  hat provides the
25170 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
25180 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
25190 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20 20 62   should.**     b
251a0 65 20 75 73 65 64 20 74 6f 20 61 63 63 65 73 73  e used to access
251b0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
251c0 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49 66 20  le on disk. ^If 
251d0 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 73  this option is s
251e0 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61 6e 20  et to.**     an 
251f0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74 68 65  empty string the
25200 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f 62 6a   default VFS obj
25210 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e 53 70  ect is used. ^Sp
25220 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
25230 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53 20 69  own.**     VFS i
25240 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49 66 20  s an error. ^If 
25250 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
25260 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
25270 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69 73 0a  e vfs option is.
25280 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74 2c 20  **     present, 
25290 74 68 65 6e 20 74 68 65 20 56 46 53 20 73 70 65  then the VFS spe
252a0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 6f 70  cified by the op
252b0 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65 63 65  tion takes prece
252c0 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20 20 20  dence over.**   
252d0 20 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73    the value pass
252e0 65 64 20 61 73 20 74 68 65 20 66 6f 75 72 74 68  ed as the fourth
252f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
25300 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
25310 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
25320 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54 68 65  >mode</b>: ^(The
25330 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
25340 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65 69  may be set to ei
25350 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77 22 2c  ther "ro", "rw",
25360 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c 20 6f  .**     "rwc", o
25370 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74 74 65  r "memory". Atte
25380 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74  mpting to set it
25390 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76 61   to any other va
253a0 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20 61 6e  lue is.**     an
253b0 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
253c0 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
253d0 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
253e0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
253f0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
25400 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
25410 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
25420 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
25430 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
25440 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
25450 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
25460 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
25470 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
25480 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69  If the mode opti
25490 6f 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a  on is set to .**
254a0 20 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20       "rw", then 
254b0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
254c0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
254d0 77 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63  write (but not c
254e0 72 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61  reate) .**     a
254f0 63 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c  ccess, as if SQL
25500 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
25510 54 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49  TE (but not SQLI
25520 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20  TE_OPEN_CREATE) 
25530 68 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e  had .**     been
25540 20 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77   set. ^Value "rw
25550 63 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74  c" is equivalent
25560 20 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68   to setting both
25570 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f   .**     SQLITE_
25580 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61  OPEN_READWRITE a
25590 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43  nd SQLITE_OPEN_C
255a0 52 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20  REATE.  ^If the 
255b0 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  mode option is.*
255c0 2a 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65  *     set to "me
255d0 6d 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72  mory" then a pur
255e0 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  e [in-memory dat
255f0 61 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65  abase] that neve
25600 72 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f  r reads.**     o
25610 72 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69  r writes from di
25620 73 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20  sk is used. ^It 
25630 69 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73  is an error to s
25640 70 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66  pecify a value f
25650 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f  or.**     the mo
25660 64 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  de parameter tha
25670 74 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69  t is less restri
25680 63 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20  ctive than that 
25690 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
256a0 20 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61      the flags pa
256b0 73 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72  ssed in the thir
256c0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
256d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
256e0 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
256f0 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68  b>cache</b>: ^Th
25700 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65  e cache paramete
25710 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
25720 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20  either "shared" 
25730 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61  or.**     "priva
25740 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74  te". ^Setting it
25750 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20   to "shared" is 
25760 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65  equivalent to se
25770 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20  tting the.**    
25780 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
25790 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20  REDCACHE bit in 
257a0 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  the flags argume
257b0 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  nt passed to.** 
257c0 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e      sqlite3_open
257d0 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20  _v2(). ^Setting 
257e0 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  the cache parame
257f0 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22  ter to "private"
25800 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69   is .**     equi
25810 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e  valent to settin
25820 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  g the SQLITE_OPE
25830 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62  N_PRIVATECACHE b
25840 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73  it..**     ^If s
25850 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25860 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65   is used and the
25870 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74   "cache" paramet
25880 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e  er is present in
25890 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69  .**     a URI fi
258a0 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75  lename, its valu
258b0 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20  e overrides any 
258c0 62 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 73  behaviour reques
258d0 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a  ted by setting.*
258e0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
258f0 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f  N_PRIVATECACHE o
25900 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  r SQLITE_OPEN_SH
25910 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a  AREDCACHE flag..
25920 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
25930 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
25940 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
25950 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
25960 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
25970 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
25980 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
25990 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
259a0 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
259b0 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
259c0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
259d0 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
259e0 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
259f0 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
25a00 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
25a10 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
25a20 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
25a30 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
25a40 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
25a50 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
25a60 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
25a70 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
25a80 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
25a90 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
25aa0 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
25ab0 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
25ac0 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
25ad0 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
25ae0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
25af0 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
25b00 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
25b10 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
25b20 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
25b30 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
25b40 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
25b50 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
25b60 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
25b70 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
25b80 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
25b90 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
25ba0 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
25bb0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
25bc0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
25bd0 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
25be0 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
25bf0 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
25c00 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
25c10 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
25c20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
25c30 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
25c40 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
25c50 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
25c60 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
25c70 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
25c80 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
25c90 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
25ca0 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
25cb0 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
25cc0 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
25cd0 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
25ce0 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
25cf0 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
25d00 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
25d10 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
25d20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
25d30 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
25d40 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
25d50 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
25d60 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
25d70 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
25d80 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
25d90 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
25da0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
25db0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
25dc0 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
25dd0 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
25de0 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
25df0 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
25e00 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
25e10 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
25e20 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
25e30 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
25e40 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
25e50 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
25e60 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
25e70 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
25e80 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
25e90 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
25ea0 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
25eb0 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
25ec0 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
25ed0 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
25ee0 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a  ix-nolock <td>.*
25ef0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
25f00 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
25f10 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
25f20 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
25f30 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a  unix-nolock"..**
25f40 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
25f50 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
25f60 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
25f70 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
25f80 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
25f90 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
25fa0 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
25fb0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
25fc0 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
25fd0 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
25fe0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
25ff0 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
26000 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
26010 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
26020 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
26030 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
26040 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
26050 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
26060 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
26070 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
26080 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
26090 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
260a0 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
260b0 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
260c0 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
260d0 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
260e0 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
260f0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
26100 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
26110 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
26120 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
26130 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
26140 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
26150 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
26160 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
26170 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
26180 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
26190 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
261a0 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
261b0 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
261c0 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
261d0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
261e0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
261f0 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
26200 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
26210 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
26220 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
26230 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
26240 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
26250 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
26260 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
26270 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
26280 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
26290 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
262a0 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
262b0 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
262c0 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
262d0 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
262e0 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
262f0 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
26300 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
26310 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
26320 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
26330 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  )..**.** <b>Note
26340 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
26350 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20  ime users:</b>  
26360 54 68 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69  The temporary di
26370 72 65 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20  rectory must be 
26380 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  set.** prior to 
26390 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  calling sqlite3_
263a0 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65  open() or sqlite
263b0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 20 4f 74  3_open_v2().  Ot
263c0 68 65 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73  herwise, various
263d0 0a 2a 2a 20 66 65 61 74 75 72 65 73 20 74 68 61  .** features tha
263e0 74 20 72 65 71 75 69 72 65 20 74 68 65 20 75 73  t require the us
263f0 65 20 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66  e of temporary f
26400 69 6c 65 73 20 6d 61 79 20 66 61 69 6c 2e 0a 2a  iles may fail..*
26410 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
26420 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f 64 69 72  sqlite3_temp_dir
26430 65 63 74 6f 72 79 5d 0a 2a 2f 0a 53 51 4c 49 54  ectory].*/.SQLIT
26440 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
26450 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
26460 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
26470 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
26480 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
26490 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
264a0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
264b0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
264c0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  ndle */.);.SQLIT
264d0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
264e0 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
264f0 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
26500 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
26510 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
26520 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
26530 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
26540 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
26550 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
26560 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
26570 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
26580 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
26590 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
265a0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
265b0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
265c0 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
265d0 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
265e0 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
265f0 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
26600 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
26610 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
26620 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
26630 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
26640 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
26650 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26660 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
26670 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
26680 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
26690 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
266a0 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
266b0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
266c0 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
266d0 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
266e0 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
266f0 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
26700 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
26710 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
26720 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
26730 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
26740 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
26750 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
26760 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
26770 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
26780 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
26790 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
267a0 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
267b0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
267c0 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
267d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
267e0 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
267f0 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
26800 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
26810 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
26820 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
26830 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
26840 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
26850 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
26860 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
26870 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
26880 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
26890 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
268a0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
268b0 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
268c0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
268d0 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
268e0 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
268f0 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
26900 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
26910 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
26920 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
26930 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
26940 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
26950 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
26960 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
26970 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
26980 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
26990 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
269a0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
269b0 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
269c0 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
269d0 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
269e0 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
269f0 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
26a00 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
26a10 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
26a20 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
26a30 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
26a40 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
26a50 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
26a60 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
26a70 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
26a80 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
26a90 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
26aa0 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
26ab0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
26ac0 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
26ad0 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
26ae0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
26af0 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
26b00 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
26b10 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
26b20 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
26b30 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
26b40 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
26b50 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
26b60 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
26b70 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
26b80 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
26b90 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
26ba0 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
26bb0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
26bc0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
26bd0 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
26be0 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
26bf0 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
26c00 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
26c10 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
26c20 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
26c30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
26c40 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
26c50 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
26c60 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
26c70 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
26c80 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
26c90 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
26ca0 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
26cb0 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
26cc0 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
26cd0 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
26ce0 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
26cf0 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
26d00 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
26d10 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
26d20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
26d30 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
26d40 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
26d50 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
26d60 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
26d70 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
26d80 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
26d90 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
26da0 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
26db0 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
26dc0 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
26dd0 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
26de0 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
26df0 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
26e00 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
26e10 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
26e20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
26e30 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
26e40 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
26e50 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  rable..*/.SQLITE
26e60 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
26e70 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
26e80 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
26e90 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
26ea0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
26eb0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
26ec0 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  t sqlite3_uri_bo
26ed0 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72  olean(const char
26ee0 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63   *zFile, const c
26ef0 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74  har *zParam, int
26f00 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49   bDefault);.SQLI
26f10 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
26f20 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69  nt64 sqlite3_uri
26f30 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
26f40 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
26f50 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
26f60 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
26f70 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
26f80 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a  nd Messages.**.*
26f90 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
26fa0 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61  rrcode() interfa
26fb0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
26fc0 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
26fd0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
26fe0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
26ff0 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  ] for the most r
27000 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c  ecent failed sql
27010 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a  ite3_* API call.
27020 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
27030 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
27040 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61  onnection]. If a
27050 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
27060 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68  failed.** but th
27070 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  e most recent AP
27080 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
27090 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
270a0 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  ue from.** sqlit
270b0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
270c0 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  undefined.  ^The
270d0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
270e0 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
270f0 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
27100 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
27110 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
27120 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
27130 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
27140 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
27150 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
27160 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
27170 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
27180 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
27190 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
271a0 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
271b0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
271c0 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
271d0 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
271e0 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
271f0 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
27200 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
27210 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
27220 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
27230 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
27240 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
27250 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
27260 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
27270 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
27280 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
27290 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
272a0 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
272b0 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
272c0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
272d0 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
272e0 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
272f0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
27300 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
27310 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
27320 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65 72  3_errstr() inter
27330 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
27340 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
27350 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20 64  e text.** that d
27360 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72 65  escribes the [re
27370 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20 55  sult code], as U
27380 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72  TF-8..** ^(Memor
27390 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72  y to hold the er
273a0 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
273b0 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e  ng is managed in
273c0 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64 20  ternally.** and 
273d0 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65 65  must not be free
273e0 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
273f0 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68  tion)^..**.** Wh
27400 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
27410 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
27420 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
27430 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
27440 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
27450 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
27460 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
27470 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
27480 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
27490 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
274a0 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
274b0 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
274c0 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
274d0 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
274e0 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
274f0 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
27500 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
27510 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
27520 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
27530 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
27540 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
27550 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
27560 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
27570 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
27580 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
27590 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
275a0 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
275b0 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
275c0 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
275d0 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
275e0 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
275f0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
27600 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
27610 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
27620 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
27630 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
27640 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
27650 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
27660 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
27670 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
27680 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
27690 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
276a0 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
276b0 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
276c0 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
276d0 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
276e0 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
276f0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
27700 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
27710 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
27720 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
27730 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
27740 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
27750 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
27760 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
27770 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
27780 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  *db);.SQLITE_API
27790 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
277a0 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
277b0 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  te3*);.SQLITE_AP
277c0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
277d0 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
277e0 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
277f0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
27800 2a 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28  *sqlite3_errstr(
27810 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
27820 49 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65  I3REF: SQL State
27830 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  ment Object.** K
27840 45 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72  EYWORDS: {prepar
27850 65 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70  ed statement} {p
27860 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27870 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ts}.**.** An ins
27880 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
27890 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
278a0 61 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61  a single SQL sta
278b0 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20  tement..** This 
278c0 6f 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75  object is variou
278d0 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22  sly known as a "
278e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
278f0 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d  nt" or a.** "com
27900 70 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d  piled SQL statem
27910 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61  ent" or simply a
27920 73 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e  s a "statement".
27930 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20  .**.** The life 
27940 6f 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f  of a statement o
27950 62 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74  bject goes somet
27960 68 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a  hing like this:.
27970 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
27980 69 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62  i> Create the ob
27990 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  ject using [sqli
279a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
279b0 5d 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a  ] or a related.*
279c0 2a 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e  *      function.
279d0 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61  .** <li> Bind va
279e0 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61  lues to [host pa
279f0 72 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20  rameters] using 
27a00 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
27a10 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74  _*().**      int
27a20 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  erfaces..** <li>
27a30 20 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20   Run the SQL by 
27a40 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
27a50 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20  _step()] one or 
27a60 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
27a70 6c 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74  li> Reset the st
27a80 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
27a90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
27aa0 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20  then go back.** 
27ab0 20 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20       to step 2. 
27ac0 20 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72   Do this zero or
27ad0 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20   more times..** 
27ae0 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65  <li> Destroy the
27af0 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
27b00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
27b10 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  )]..** </ol>.**.
27b20 2a 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75  ** Refer to docu
27b30 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  mentation on ind
27b40 69 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20  ividual methods 
27b50 61 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69  above for additi
27b60 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  onal.** informat
27b70 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
27b80 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73  struct sqlite3_s
27b90 74 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  tmt sqlite3_stmt
27ba0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27bb0 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69  F: Run-time Limi
27bc0 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  ts.**.** ^(This 
27bd0 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73  interface allows
27be0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72   the size of var
27bf0 69 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20  ious constructs 
27c00 74 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a  to be limited.**
27c10 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e   on a connection
27c20 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62   by connection b
27c30 61 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74  asis.  The first
27c40 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
27c50 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
27c60 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65  onnection] whose
27c70 20 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20   limit is to be 
27c80 73 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20  set or queried. 
27c90 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   The.** second p
27ca0 61 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20  arameter is one 
27cb0 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61  of the [limit ca
27cc0 74 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64  tegories] that d
27cd0 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73  efine a.** class
27ce0 20 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74   of constructs t
27cf0 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65  o be size limite
27d00 64 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61  d.  The third pa
27d10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
27d20 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20  * new limit for 
27d30 74 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29  that construct.)
27d40 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ^.**.** ^If the 
27d50 6e 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e  new limit is a n
27d60 65 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20  egative number, 
27d70 74 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63  the limit is unc
27d80 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72  hanged..** ^(For
27d90 20 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65   each limit cate
27da0 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49  gory SQLITE_LIMI
27db0 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68  T_<i>NAME</i> th
27dc0 65 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69  ere is a .** [li
27dd0 6d 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65  mits | hard uppe
27de0 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20  r bound].** set 
27df0 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
27e00 62 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73  by a C preproces
27e10 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64  sor macro called
27e20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51  .** [limits | SQ
27e30 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45  LITE_MAX_<i>NAME
27e40 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22  </i>]..** (The "
27e50 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20  _LIMIT_" in the 
27e60 6e 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20  name is changed 
27e70 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a  to "_MAX_".))^.*
27e80 2a 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69  * ^Attempts to i
27e90 6e 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20  ncrease a limit 
27ea0 61 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75  above its hard u
27eb0 70 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a  pper bound are.*
27ec0 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63  * silently trunc
27ed0 61 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64  ated to the hard
27ee0 20 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a   upper bound..**
27ef0 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20  .** ^Regardless 
27f00 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
27f10 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
27f20 63 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a  changed, the .**
27f30 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
27f40 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  )] interface ret
27f50 75 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76  urns the prior v
27f60 61 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69  alue of the limi
27f70 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f  t..** ^Hence, to
27f80 20 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e   find the curren
27f90 74 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d  t value of a lim
27fa0 69 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67  it without chang
27fb0 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c  ing it,.** simpl
27fc0 79 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e  y invoke this in
27fd0 74 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65  terface with the
27fe0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
27ff0 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a   set to -1..**.*
28000 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  * Run-time limit
28010 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
28020 6f 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63  or use in applic
28030 61 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61  ations that mana
28040 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72  ge.** both their
28050 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61   own internal da
28060 74 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20  tabase and also 
28070 64 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61  databases that a
28080 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a  re controlled.**
28090 20 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78   by untrusted ex
280a0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20  ternal sources. 
280b0 20 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c   An example appl
280c0 69 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65  ication might be
280d0 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65   a.** web browse
280e0 72 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f  r that has its o
280f0 77 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72  wn databases for
28100 20 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79   storing history
28110 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65   and.** separate
28120 20 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72   databases contr
28130 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72  olled by JavaScr
28140 69 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  ipt applications
28150 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f   downloaded.** o
28160 66 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e  ff the Internet.
28170 20 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64    The internal d
28180 61 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20  atabases can be 
28190 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72  given the.** lar
281a0 67 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69  ge, default limi
281b0 74 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d  ts.  Databases m
281c0 61 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e  anaged by extern
281d0 61 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a  al sources can.*
281e0 2a 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20  * be given much 
281f0 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64  smaller limits d
28200 65 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65  esigned to preve
28210 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73  nt a denial of s
28220 65 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b  ervice.** attack
28230 2e 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69  .  Developers mi
28240 67 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f  ght also want to
28250 20 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65   use the [sqlite
28260 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
28270 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  ()].** interface
28280 20 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74   to further cont
28290 72 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51  rol untrusted SQ
282a0 4c 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20  L.  The size of 
282b0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
282c0 63 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e  created by an un
282d0 74 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63  trusted script c
282e0 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20  an be contained 
282f0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61  using the.** [ma
28300 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50  x_page_count] [P
28310 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65  RAGMA]..**.** Ne
28320 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74  w run-time limit
28330 20 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20   categories may 
28340 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
28350 72 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a  re releases..*/.
28360 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
28370 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c  qlite3_limit(sql
28380 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69  ite3*, int id, i
28390 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a  nt newVal);../*.
283a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
283b0 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65  -Time Limit Cate
283c0 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52  gories.** KEYWOR
283d0 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67  DS: {limit categ
283e0 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74  ory} {*limit cat
283f0 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54  egories}.**.** T
28400 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64  hese constants d
28410 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65  efine various pe
28420 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73  rformance limits
28430 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
28440 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74  lowered at run-t
28450 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ime using [sqlit
28460 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20  e3_limit()]..** 
28470 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20  The synopsis of 
28480 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20  the meanings of 
28490 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69  the various limi
284a0 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f  ts is shown belo
284b0 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c  w..** Additional
284c0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
284d0 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69  available at [li
284e0 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e  mits | Limits in
284f0 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20   SQLite]..**.** 
28500 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
28510 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20  _LIMIT_LENGTH]] 
28520 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28530 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  IT_LENGTH</dt>.*
28540 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28550 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74  m size of any st
28560 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20  ring or BLOB or 
28570 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79  table row, in by
28580 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  tes.<dd>)^.**.**
28590 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
285a0 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  SQL_LENGTH]] ^(<
285b0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
285c0 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  SQL_LENGTH</dt>.
285d0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
285e0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20  um length of an 
285f0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69  SQL statement, i
28600 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a  n bytes.</dd>)^.
28610 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28620 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28  IMIT_COLUMN]] ^(
28630 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28640 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20  _COLUMN</dt>.** 
28650 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28660 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
28670 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66  s in a table def
28680 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68  inition or in th
28690 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20  e.** result set 
286a0 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72  of a [SELECT] or
286b0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
286c0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
286d0 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72  n an index.** or
286e0 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20   in an ORDER BY 
286f0 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75  or GROUP BY clau
28700 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  se.</dd>)^.**.**
28710 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28720 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  EXPR_DEPTH]] ^(<
28730 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28740 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a  EXPR_DEPTH</dt>.
28750 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
28760 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20  um depth of the 
28770 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e  parse tree on an
28780 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64  y expression.</d
28790 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
287a0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
287b0 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64  ND_SELECT]] ^(<d
287c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
287d0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
287e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
287f0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
28800 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
28810 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
28820 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
28830 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
28840 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c  IT_VDBE_OP]] ^(<
28850 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28860 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20  VDBE_OP</dt>.** 
28870 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
28880 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75  number of instru
28890 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74  ctions in a virt
288a0 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67  ual machine prog
288b0 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69  ram.** used to i
288c0 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20  mplement an SQL 
288d0 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73  statement.  This
288e0 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75   limit is not cu
288f0 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72  rrently.** enfor
28900 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74  ced, though that
28910 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20   might be added 
28920 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72  in some future r
28930 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c  elease of.** SQL
28940 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ite.</dd>)^.**.*
28950 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
28960 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20  _FUNCTION_ARG]] 
28970 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28980 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c  IT_FUNCTION_ARG<
28990 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
289a0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
289b0 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61  f arguments on a
289c0 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29   function.</dd>)
289d0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
289e0 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d  _LIMIT_ATTACHED]
289f0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
28a00 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64  IMIT_ATTACHED</d
28a10 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
28a20 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
28a30 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68  [ATTACH | attach
28a40 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e  ed databases].)^
28a50 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
28a60 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
28a70 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d  PATTERN_LENGTH]]
28a80 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
28a90 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
28aa0 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  ERN_LENGTH</dt>.
28ab0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
28ac0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  um length of the
28ad0 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e   pattern argumen
28ae0 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20  t to the [LIKE] 
28af0 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65  or.** [GLOB] ope
28b00 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a  rators.</dd>)^.*
28b10 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
28b20 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
28b30 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  BER]].** ^(<dt>S
28b40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
28b50 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e  ABLE_NUMBER</dt>
28b60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28b70 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72  mum index number
28b80 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74   of any [paramet
28b90 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74  er] in an SQL st
28ba0 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a  atement.)^.**.**
28bb0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28bc0 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20  TRIGGER_DEPTH]] 
28bd0 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
28be0 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
28bf0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
28c00 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
28c10 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20  f recursion for 
28c20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e  triggers.</dd>)^
28c30 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
28c40 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
28c50 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  T_LENGTH        
28c60 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64              0.#d
28c70 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
28c80 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20  IT_SQL_LENGTH   
28c90 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
28ca0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
28cb0 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20  MIT_COLUMN      
28cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a                2.
28cd0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
28ce0 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20  IMIT_EXPR_DEPTH 
28cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33                 3
28d00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
28d10 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
28d20 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
28d30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
28d40 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20  _LIMIT_VDBE_OP  
28d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28d60 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   5.#define SQLIT
28d70 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
28d80 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20  _ARG            
28d90 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
28da0 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
28db0 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
28dc0 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c     7.#define SQL
28dd0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
28de0 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20  ATTERN_LENGTH   
28df0 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
28e00 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
28e10 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20  BLE_NUMBER      
28e20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
28e30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47  QLITE_LIMIT_TRIG
28e40 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20  GER_DEPTH       
28e50 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43       10../*.** C
28e60 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69  API3REF: Compili
28e70 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  ng An SQL Statem
28e80 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ent.** KEYWORDS:
28e90 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20   {SQL statement 
28ea0 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20  compiler}.**.** 
28eb0 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51  To execute an SQ
28ec0 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74  L query, it must
28ed0 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c   first be compil
28ee0 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63  ed into a byte-c
28ef0 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75  ode.** program u
28f00 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73  sing one of thes
28f10 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
28f20 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
28f30 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61  ment, "db", is a
28f40 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
28f50 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20  ction] obtained 
28f60 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20  from a.** prior 
28f70 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20  successful call 
28f80 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
28f90 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
28fa0 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b  en_v2()] or.** [
28fb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
28fc0 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65  ].  The database
28fd0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
28fe0 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63   not have been c
28ff0 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  losed..**.** The
29000 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
29010 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65  , "zSql", is the
29020 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65   statement to be
29030 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64   compiled, encod
29040 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20  ed.** as either 
29050 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e  UTF-8 or UTF-16.
29060 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72    The sqlite3_pr
29070 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69  epare() and sqli
29080 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
29090 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75  .** interfaces u
290a0 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71  se UTF-8, and sq
290b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
290c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  ) and sqlite3_pr
290d0 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20  epare16_v2().** 
290e0 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a  use UTF-16..**.*
290f0 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20  * ^If the nByte 
29100 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73  argument is less
29110 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e   than zero, then
29120 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70   zSql is read up
29130 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   to the.** first
29140 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
29150 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e  . ^If nByte is n
29160 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
29170 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69  n it is the maxi
29180 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  mum.** number of
29190 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f    bytes read fro
291a0 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e  m zSql.  ^When n
291b0 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  Byte is non-nega
291c0 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71  tive, the.** zSq
291d0 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74  l string ends at
291e0 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73   either the firs
291f0 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30  t '\000' or '\u0
29200 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f  000' character o
29210 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74  r.** the nByte-t
29220 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65  h byte, whicheve
29230 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49  r comes first. I
29240 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f  f the caller kno
29250 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73  ws.** that the s
29260 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69  upplied string i
29270 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  s nul-terminated
29280 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  , then there is 
29290 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f  a small.** perfo
292a0 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65  rmance advantage
292b0 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79   to be gained by
292c0 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74   passing an nByt
292d0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
292e0 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20  .** is equal to 
292f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
29300 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74  tes in the input
29310 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75   string <i>inclu
29320 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20  ding</i>.** the 
29330 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62  nul-terminator b
29340 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76  ytes as this sav
29350 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68  es SQLite from h
29360 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65  aving to.** make
29370 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69   a copy of the i
29380 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  nput string..**.
29390 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73  ** ^If pzTail is
293a0 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a   not NULL then *
293b0 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74  pzTail is made t
293c0 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66  o point to the f
293d0 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73  irst byte.** pas
293e0 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65  t the end of the
293f0 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65   first SQL state
29400 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54  ment in zSql.  T
29410 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
29420 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68  ly.** compile th
29430 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e  e first statemen
29440 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70  t in zSql, so *p
29450 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f  zTail is left po
29460 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61  inting to.** wha
29470 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70  t remains uncomp
29480 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70  iled..**.** ^*pp
29490 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69  Stmt is left poi
294a0 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69  nting to a compi
294b0 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  led [prepared st
294c0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61  atement] that ca
294d0 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64  n be.** executed
294e0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
294f0 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68  step()].  ^If th
29500 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c  ere is an error,
29510 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a   *ppStmt is set.
29520 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66  ** to NULL.  ^If
29530 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20   the input text 
29540 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20  contains no SQL 
29550 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73  (if the input is
29560 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72   an empty.** str
29570 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74  ing or a comment
29580 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69  ) then *ppStmt i
29590 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  s set to NULL..*
295a0 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72  * The calling pr
295b0 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f  ocedure is respo
295c0 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74  nsible for delet
295d0 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64  ing the compiled
295e0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
295f0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
29600 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74  _finalize()] aft
29610 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68  er it has finish
29620 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70  ed with it..** p
29630 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65  pStmt may not be
29640 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e   NULL..**.** ^On
29650 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71   success, the sq
29660 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
29670 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e  family of routin
29680 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
29690 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77  E_OK];.** otherw
296a0 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
296b0 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
296c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
296d0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20  e3_prepare_v2() 
296e0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
296f0 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72  are16_v2() inter
29700 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63  faces are.** rec
29710 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c  ommended for all
29720 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54   new programs. T
29730 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74  he two older int
29740 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61  erfaces are reta
29750 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b  ined.** for back
29760 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
29770 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75  ity, but their u
29780 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65  se is discourage
29790 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76  d..** ^In the "v
297a0 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  2" interfaces, t
297b0 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74  he prepared stat
297c0 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73  ement.** that is
297d0 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b   returned (the [
297e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
297f0 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61  ject) contains a
29800 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
29810 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78  original SQL tex
29820 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74  t. This causes t
29830 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
29840 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f  ()] interface to
29850 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65  .** behave diffe
29860 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20  rently in three 
29870 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  ways:.**.** <ol>
29880 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20  .** <li>.** ^If 
29890 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
298a0 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73  ema changes, ins
298b0 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e  tead of returnin
298c0 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  g [SQLITE_SCHEMA
298d0 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79  ] as it.** alway
298e0 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73  s used to do, [s
298f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
29900 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
29910 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20  y recompile the 
29920 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
29930 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20   and try to run 
29940 69 74 20 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c  it again..** </l
29950 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a  i>.**.** <li>.**
29960 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20   ^When an error 
29970 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33  occurs, [sqlite3
29980 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65  _step()] will re
29990 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20  turn one of the 
299a0 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72  detailed.** [err
299b0 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78  or codes] or [ex
299c0 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64  tended error cod
299d0 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63  es].  ^The legac
299e0 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74  y behavior was t
299f0 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hat.** [sqlite3_
29a00 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e  step()] would on
29a10 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65  ly return a gene
29a20 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ric [SQLITE_ERRO
29a30 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a  R] result code.*
29a40 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  * and the applic
29a50 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65  ation would have
29a60 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e   to make a secon
29a70 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  d call to [sqlit
29a80 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69  e3_reset()].** i
29a90 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20  n order to find 
29aa0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63  the underlying c
29ab0 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62  ause of the prob
29ac0 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76  lem. With the "v
29ad0 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e  2" prepare.** in
29ae0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e  terfaces, the un
29af0 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20  derlying reason 
29b00 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73  for the error is
29b10 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
29b20 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  ately..** </li>.
29b30 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49  **.** <li>.** ^I
29b40 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76  f the specific v
29b50 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70  alue bound to [p
29b60 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20  arameter | host 
29b70 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
29b80 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75  e .** WHERE clau
29b90 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e  se might influen
29ba0 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66  ce the choice of
29bb0 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20   query plan for 
29bc0 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20  a statement,.** 
29bd0 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65  then the stateme
29be0 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d  nt will be autom
29bf0 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
29c00 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65  led, as if there
29c10 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20   had been .** a 
29c20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f  schema change, o
29c30 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71  n the first  [sq
29c40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61  lite3_step()] ca
29c50 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79  ll following any
29c60 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68   change.** to th
29c70 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
29c80 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d  text | bindings]
29c90 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65   of that [parame
29ca0 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73  ter]. .** ^The s
29cb0 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66  pecific value of
29cc0 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70   WHERE-clause [p
29cd0 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20  arameter] might 
29ce0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a  influence the .*
29cf0 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  * choice of quer
29d00 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61  y plan if the pa
29d10 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c  rameter is the l
29d20 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66  eft-hand side of
29d30 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20   a [LIKE].** or 
29d40 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20  [GLOB] operator 
29d50 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  or if the parame
29d60 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20  ter is compared 
29d70 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f  to an indexed co
29d80 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20  lumn.** and the 
29d90 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53  [SQLITE_ENABLE_S
29da0 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  TAT3] compile-ti
29db0 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61  me option is ena
29dc0 62 6c 65 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a  bled..** the .**
29dd0 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a   </li>.** </ol>.
29de0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
29df0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
29e00 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
29e10 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
29e20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
29e30 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
29e40 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
29e50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
29e60 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  TF-8 encoded */.
29e70 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
29e80 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
29e90 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
29ea0 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
29eb0 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
29ec0 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
29ed0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
29ee0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
29ef0 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  har **pzTail    
29f00 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
29f10 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
29f20 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
29f30 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
29f40 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
29f50 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
29f60 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
29f70 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
29f80 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
29f90 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
29fa0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
29fb0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
29fc0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
29fd0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
29fe0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
29ff0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2a000 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2a010 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2a020 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2a030 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2a040 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
2a050 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2a060 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2a070 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2a080 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2a090 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
2a0a0 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
2a0b0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
2a0c0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
2a0d0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2a0e0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
2a0f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
2a100 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
2a110 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
2a120 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
2a130 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
2a140 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
2a150 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
2a160 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
2a170 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
2a180 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
2a190 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
2a1a0 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
2a1b0 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
2a1c0 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
2a1d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2a1e0 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
2a1f0 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
2a200 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
2a210 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
2a220 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2a230 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
2a240 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
2a250 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
2a260 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
2a270 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
2a280 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
2a290 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
2a2a0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
2a2b0 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
2a2c0 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
2a2d0 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
2a2e0 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
2a2f0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
2a300 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
2a310 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
2a320 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
2a330 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
2a340 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
2a350 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
2a360 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
2a370 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
2a380 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
2a390 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
2a3a0 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
2a3b0 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
2a3c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
2a3d0 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
2a3e0 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
2a3f0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
2a400 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2a410 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2a420 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
2a430 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2a440 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2a450 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
2a460 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2a470 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
2a480 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
2a490 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
2a4a0 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
2a4b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a4c0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
2a4d0 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
2a4e0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
2a4f0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
2a500 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
2a510 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a520 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
2a530 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
2a540 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
2a550 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
2a560 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
2a570 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
2a580 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2a590 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
2a5a0 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
2a5b0 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
2a5c0 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
2a5d0 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
2a5e0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
2a5f0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
2a600 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2a610 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
2a620 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
2a630 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
2a640 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
2a650 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
2a660 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
2a670 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
2a680 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
2a690 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
2a6a0 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
2a6b0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
2a6c0 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
2a6d0 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
2a6e0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
2a6f0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
2a700 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
2a710 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
2a720 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2a730 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2a740 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
2a750 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
2a760 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
2a770 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
2a780 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
2a790 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
2a7a0 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
2a7b0 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
2a7c0 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
2a7d0 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
2a7e0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
2a7f0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
2a800 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
2a810 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
2a820 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
2a830 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
2a840 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
2a850 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
2a860 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
2a870 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
2a880 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
2a890 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
2a8a0 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
2a8b0 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
2a8c0 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
2a8d0 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
2a8e0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
2a8f0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
2a900 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
2a910 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
2a920 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
2a930 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
2a940 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
2a950 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
2a960 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
2a970 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
2a980 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
2a990 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
2a9a0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
2a9b0 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 53 51  s on disk..*/.SQ
2a9c0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a9d0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
2a9e0 6c 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ly(sqlite3_stmt 
2a9f0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2aa00 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d  CAPI3REF: Determ
2aa10 69 6e 65 20 49 66 20 41 20 50 72 65 70 61 72 65  ine If A Prepare
2aa20 64 20 53 74 61 74 65 6d 65 6e 74 20 48 61 73 20  d Statement Has 
2aa30 42 65 65 6e 20 52 65 73 65 74 0a 2a 2a 0a 2a 2a  Been Reset.**.**
2aa40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2aa50 6d 74 5f 62 75 73 79 28 53 29 20 69 6e 74 65 72  mt_busy(S) inter
2aa60 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
2aa70 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 20  e (non-zero) if 
2aa80 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2aa90 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 68 61   statement] S ha
2aaa0 73 20 62 65 65 6e 20 73 74 65 70 70 65 64 20 61  s been stepped a
2aab0 74 20 6c 65 61 73 74 20 6f 6e 63 65 20 75 73 69  t least once usi
2aac0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2aad0 73 74 65 70 28 53 29 5d 20 62 75 74 20 68 61 73  step(S)] but has
2aae0 20 6e 6f 74 20 72 75 6e 20 74 6f 20 63 6f 6d 70   not run to comp
2aaf0 6c 65 74 69 6f 6e 20 61 6e 64 2f 6f 72 20 68 61  letion and/or ha
2ab00 73 20 6e 6f 74 20 0a 2a 2a 20 62 65 65 6e 20 72  s not .** been r
2ab10 65 73 65 74 20 75 73 69 6e 67 20 5b 73 71 6c 69  eset using [sqli
2ab20 74 65 33 5f 72 65 73 65 74 28 53 29 5d 2e 20 20  te3_reset(S)].  
2ab30 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74 6d  ^The sqlite3_stm
2ab40 74 5f 62 75 73 79 28 53 29 0a 2a 2a 20 69 6e 74  t_busy(S).** int
2ab50 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 66  erface returns f
2ab60 61 6c 73 65 20 69 66 20 53 20 69 73 20 61 20 4e  alse if S is a N
2ab70 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 49 66  ULL pointer.  If
2ab80 20 53 20 69 73 20 6e 6f 74 20 61 20 0a 2a 2a 20   S is not a .** 
2ab90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
2aba0 20 69 73 20 6e 6f 74 20 61 20 70 6f 69 6e 74 65   is not a pointe
2abb0 72 20 74 6f 20 61 20 76 61 6c 69 64 20 5b 70 72  r to a valid [pr
2abc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2abd0 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2c 20 74 68 65  ].** object, the
2abe0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
2abf0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2ac00 70 72 6f 62 61 62 6c 79 20 75 6e 64 65 73 69 72  probably undesir
2ac10 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  able..**.** This
2ac20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
2ac30 65 20 75 73 65 64 20 69 6e 20 63 6f 6d 62 69 6e  e used in combin
2ac40 61 74 69 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 6e  ation [sqlite3_n
2ac50 65 78 74 5f 73 74 6d 74 28 29 5d 0a 2a 2a 20 74  ext_stmt()].** t
2ac60 6f 20 6c 6f 63 61 74 65 20 61 6c 6c 20 70 72 65  o locate all pre
2ac70 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
2ac80 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2ac90 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a 2a 20   a database .** 
2aca0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
2acb0 61 72 65 20 69 6e 20 6e 65 65 64 20 6f 66 20 62  are in need of b
2acc0 65 69 6e 67 20 72 65 73 65 74 2e 20 20 54 68 69  eing reset.  Thi
2acd0 73 20 63 61 6e 20 62 65 20 75 73 65 64 2c 0a 2a  s can be used,.*
2ace0 2a 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  * for example, i
2acf0 6e 20 64 69 61 67 6e 6f 73 74 69 63 20 72 6f 75  n diagnostic rou
2ad00 74 69 6e 65 73 20 74 6f 20 73 65 61 72 63 68 20  tines to search 
2ad10 66 6f 72 20 70 72 65 70 61 72 65 64 20 0a 2a 2a  for prepared .**
2ad20 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
2ad30 20 61 72 65 20 68 6f 6c 64 69 6e 67 20 61 20 74   are holding a t
2ad40 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2e  ransaction open.
2ad50 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2ad60 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
2ad70 62 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d  busy(sqlite3_stm
2ad80 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2ad90 33 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c  3REF: Dynamicall
2ada0 79 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62  y Typed Value Ob
2adb0 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ject.** KEYWORDS
2adc0 3a 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  : {protected sql
2add0 69 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70  ite3_value} {unp
2ade0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2adf0 5f 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51  _value}.**.** SQ
2ae00 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71  Lite uses the sq
2ae10 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2ae20 63 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20  ct to represent 
2ae30 61 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68  all values.** th
2ae40 61 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64  at can be stored
2ae50 20 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74   in a database t
2ae60 61 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65  able. SQLite use
2ae70 73 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67  s dynamic typing
2ae80 0a 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75  .** for the valu
2ae90 65 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e  es it stores.  ^
2aea0 56 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e  Values stored in
2aeb0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2aec0 62 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65  bjects.** can be
2aed0 20 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74   integers, float
2aee0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73  ing point values
2aef0 2c 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73  , strings, BLOBs
2af00 2c 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  , or NULL..**.**
2af10 20 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75   An sqlite3_valu
2af20 65 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20  e object may be 
2af30 65 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65  either "protecte
2af40 64 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74  d" or "unprotect
2af50 65 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74  ed"..** Some int
2af60 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2af70 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2af80 74 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65  te3_value.  Othe
2af90 72 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  r interfaces.** 
2afa0 77 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68  will accept eith
2afb0 65 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f  er a protected o
2afc0 72 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64  r an unprotected
2afd0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2afe0 2a 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61  ** Every interfa
2aff0 63 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20  ce that accepts 
2b000 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72  sqlite3_value ar
2b010 67 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65  guments specifie
2b020 73 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20  s.** whether or 
2b030 6e 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20  not it requires 
2b040 61 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  a protected sqli
2b050 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  te3_value..**.**
2b060 20 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74   The terms "prot
2b070 65 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72  ected" and "unpr
2b080 6f 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74  otected" refer t
2b090 6f 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  o whether or not
2b0a0 0a 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68  .** a mutex is h
2b0b0 65 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61  eld.  An interna
2b0c0 6c 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20  l mutex is held 
2b0d0 66 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a  for a protected.
2b0e0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2b0f0 20 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d   object but no m
2b100 75 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72  utex is held for
2b110 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a   an unprotected.
2b120 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
2b130 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c   object.  If SQL
2b140 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
2b150 74 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72  to be single-thr
2b160 65 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b  eaded.** (with [
2b170 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
2b180 45 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73  E=0] and with [s
2b190 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
2b1a0 65 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30  e()] returning 0
2b1b0 29 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74  ).** or if SQLit
2b1c0 65 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20  e is run in one 
2b1d0 6f 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78  of reduced mutex
2b1e0 20 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49   modes .** [SQLI
2b1f0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2b200 54 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49  THREAD] or [SQLI
2b210 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
2b220 48 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74  HREAD].** then t
2b230 68 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69  here is no disti
2b240 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70  nction between p
2b250 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70  rotected and unp
2b260 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69  rotected.** sqli
2b270 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b280 73 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62  s and they can b
2b290 65 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e  e used interchan
2b2a0 67 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72  geably.  However
2b2b0 2c 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d  ,.** for maximum
2b2c0 20 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74   code portabilit
2b2d0 79 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  y it is recommen
2b2e0 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
2b2f0 74 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d  tions.** still m
2b300 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
2b310 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74  ion between prot
2b320 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74  ected and unprot
2b330 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2b340 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65  _value objects e
2b350 76 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72  ven when not str
2b360 69 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a  ictly required..
2b370 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2b380 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2b390 20 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64   that are passed
2b3a0 20 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69   as parameters i
2b3b0 6e 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65  nto the.** imple
2b3c0 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70  mentation of [ap
2b3d0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2b3e0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2b3f0 20 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a   are protected..
2b400 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2b410 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74  value object ret
2b420 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
2b430 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2b440 65 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63  e()] is unprotec
2b450 74 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63  ted..** Unprotec
2b460 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2b470 65 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e  e objects may on
2b480 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a  ly be used with.
2b490 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  ** [sqlite3_resu
2b4a0 6c 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20  lt_value()] and 
2b4b0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2b4c0 6c 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b  lue()]..** The [
2b4d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2b4e0 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c  ob | sqlite3_val
2b4f0 75 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c  ue_type()] famil
2b500 79 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y of.** interfac
2b510 65 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65  es require prote
2b520 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2b530 75 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74  ue objects..*/.t
2b540 79 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65  ypedef struct Me
2b550 6d 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b  m sqlite3_value;
2b560 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2b570 3a 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43  : SQL Function C
2b580 6f 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a  ontext Object.**
2b590 0a 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20  .** The context 
2b5a0 69 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20  in which an SQL 
2b5b0 66 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65  function execute
2b5c0 73 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61  s is stored in a
2b5d0 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e  n.** sqlite3_con
2b5e0 74 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41  text object.  ^A
2b5f0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73   pointer to an s
2b600 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
2b610 62 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61  bject.** is alwa
2b620 79 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  ys first paramet
2b630 65 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69  er to [applicati
2b640 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2b650 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68  unctions]..** Th
2b660 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2b670 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2b680 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
2b690 6e 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73  n will pass this
2b6a0 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f  .** pointer thro
2b6b0 75 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74  ugh into calls t
2b6c0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  o [sqlite3_resul
2b6d0 74 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f  t_int | sqlite3_
2b6e0 72 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73  result()],.** [s
2b6f0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2b700 5f 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71  _context()], [sq
2b710 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2b720 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2b730 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
2b740 65 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67  e()], [sqlite3_g
2b750 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a  et_auxdata()],.*
2b760 2a 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65  * and/or [sqlite
2b770 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d  3_set_auxdata()]
2b780 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2b790 75 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  uct sqlite3_cont
2b7a0 65 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext sqlite3_cont
2b7b0 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ext;../*.** CAPI
2b7c0 33 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61  3REF: Binding Va
2b7d0 6c 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64  lues To Prepared
2b7e0 20 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b   Statements.** K
2b7f0 45 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70  EYWORDS: {host p
2b800 61 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20  arameter} {host 
2b810 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73  parameters} {hos
2b820 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65  t parameter name
2b830 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  }.** KEYWORDS: {
2b840 53 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  SQL parameter} {
2b850 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20  SQL parameters} 
2b860 7b 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69  {parameter bindi
2b870 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74  ng}.**.** ^(In t
2b880 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
2b890 20 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b   text input to [
2b8a0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b8b0 76 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61  v2()] and its va
2b8c0 72 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72  riants,.** liter
2b8d0 61 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61  als may be repla
2b8e0 63 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65  ced by a [parame
2b8f0 74 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65  ter] that matche
2b900 73 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69  s one of followi
2b910 6e 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a  ng.** templates:
2b920 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2b930 6c 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20  li>  ?.** <li>  
2b940 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56  ?NNN.** <li>  :V
2b950 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56  VV.** <li>  @VVV
2b960 0a 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a  .** <li>  $VVV.*
2b970 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e  * </ul>.**.** In
2b980 20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61   the templates a
2b990 62 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73  bove, NNN repres
2b9a0 65 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20  ents an integer 
2b9b0 6c 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20  literal,.** and 
2b9c0 56 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61  VVV represents a
2b9d0 6e 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69  n alphanumeric i
2b9e0 64 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54  dentifier.)^  ^T
2b9f0 68 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65  he values of the
2ba00 73 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  se.** parameters
2ba10 20 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68   (also called "h
2ba20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61  ost parameter na
2ba30 6d 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72  mes" or "SQL par
2ba40 61 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e  ameters").** can
2ba50 20 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68   be set using th
2ba60 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2ba70 28 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69  () routines defi
2ba80 6e 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20  ned here..**.** 
2ba90 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2baa0 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
2bab0 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74  e3_bind_*() rout
2bac0 69 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a  ines is always.*
2bad0 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  * a pointer to t
2bae0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
2baf0 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
2bb00 64 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74  d from.** [sqlit
2bb10 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2bb20 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73   or its variants
2bb30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
2bb40 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
2bb50 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
2bb60 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74   SQL parameter t
2bb70 6f 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68  o be set..** ^Th
2bb80 65 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70  e leftmost SQL p
2bb90 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
2bba0 69 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68  index of 1.  ^Wh
2bbb0 65 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  en the same name
2bbc0 64 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74  d.** SQL paramet
2bbd0 65 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20  er is used more 
2bbe0 74 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e  than once, secon
2bbf0 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74  d and subsequent
2bc00 0a 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20  .** occurrences 
2bc10 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e  have the same in
2bc20 64 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74  dex as the first
2bc30 20 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20   occurrence..** 
2bc40 5e 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e  ^The index for n
2bc50 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20  amed parameters 
2bc60 63 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70  can be looked up
2bc70 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73   using the.** [s
2bc80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2bc90 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41  meter_index()] A
2bca0 50 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20  PI if desired.  
2bcb0 5e 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f  ^The index.** fo
2bcc0 72 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74  r "?NNN" paramet
2bcd0 65 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65  ers is the value
2bce0 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65   of NNN..** ^The
2bcf0 20 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20   NNN value must 
2bd00 62 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64  be between 1 and
2bd10 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69   the [sqlite3_li
2bd20 6d 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65  mit()].** parame
2bd30 74 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ter [SQLITE_LIMI
2bd40 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
2bd50 52 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75  R] (default valu
2bd60 65 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e  e: 999)..**.** ^
2bd70 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
2bd80 6e 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  nt is the value 
2bd90 74 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70  to bind to the p
2bda0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
2bdb0 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
2bdc0 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
2bdd0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
2bde0 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
2bdf0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
2be00 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
2be10 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
2be20 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
2be30 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
2be40 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
2be50 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
2be60 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
2be70 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
2be80 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
2be90 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2bea0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2beb0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2bec0 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
2bed0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
2bee0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
2bef0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
2bf00 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2bf10 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
2bf20 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
2bf30 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
2bf40 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
2bf50 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2bf60 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
2bf70 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
2bf80 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2bf90 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
2bfa0 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
2bfb0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
2bfc0 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
2bfd0 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
2bfe0 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
2bff0 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74  _text16() then t
2c000 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
2c010 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
2c020 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
2c030 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
2c040 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
2c050 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
2c060 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
2c070 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
2c080 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
2c090 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
2c0a0 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
2c0b0 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
2c0c0 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
2c0d0 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
2c0e0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
2c0f0 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
2c100 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
2c110 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
2c120 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
2c130 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
2c140 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
2c150 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
2c160 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2c170 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
2c180 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
2c190 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
2c1a0 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
2c1b0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
2c1c0 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
2c1d0 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
2c1e0 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2c1f0 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
2c200 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
2c210 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
2c220 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
2c230 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
2c240 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
2c250 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
2c260 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
2c270 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
2c280 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a  3_bind_blob(),.*
2c290 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
2c2a0 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  ext(), or sqlite
2c2b0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
2c2c0 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20  fails.  .** ^If 
2c2d0 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
2c2e0 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
2c2f0 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
2c300 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
2c310 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
2c320 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
2c330 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
2c340 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
2c350 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
2c360 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
2c370 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
2c380 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
2c390 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
2c3a0 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
2c3b0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
2c3c0 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
2c3d0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
2c3e0 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
2c3f0 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
2c400 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2c410 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
2c420 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
2c430 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
2c440 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
2c450 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
2c460 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
2c470 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
2c480 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
2c490 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
2c4a0 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
2c4b0 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
2c4c0 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
2c4d0 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
2c4e0 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
2c4f0 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
2c500 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
2c510 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
2c520 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
2c530 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
2c540 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
2c550 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
2c560 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
2c570 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
2c580 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
2c590 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
2c5a0 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
2c5b0 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
2c5c0 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
2c5d0 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
2c5e0 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
2c5f0 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
2c600 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
2c610 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
2c620 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
2c630 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c640 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
2c650 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c660 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
2c670 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2c680 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
2c690 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
2c6a0 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
2c6b0 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
2c6c0 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
2c6d0 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
2c6e0 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
2c6f0 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
2c700 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
2c710 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2c720 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
2c730 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
2c740 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
2c750 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
2c760 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
2c770 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
2c780 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
2c790 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
2c7a0 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
2c7b0 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
2c7c0 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
2c7d0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
2c7e0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
2c7f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
2c800 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
2c810 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
2c820 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
2c830 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
2c840 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
2c850 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
2c860 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
2c870 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
2c880 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
2c890 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
2c8a0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
2c8b0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
2c8c0 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
2c8d0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2c8e0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2c8f0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
2c900 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2c910 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2c920 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
2c930 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2c940 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2c950 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c960 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c  e3_bind_blob(sql
2c970 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2c980 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
2c990 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
2c9a0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
2c9b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2c9c0 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  d_double(sqlite3
2c9d0 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75  _stmt*, int, dou
2c9e0 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ble);.SQLITE_API
2c9f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2ca00 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
2ca10 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
2ca20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2ca30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
2ca40 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
2ca50 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
2ca60 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  t64);.SQLITE_API
2ca70 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2ca80 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73  d_null(sqlite3_s
2ca90 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  tmt*, int);.SQLI
2caa0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2cab0 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
2cac0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2cad0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
2cae0 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
2caf0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
2cb00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2cb10 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  d_text16(sqlite3
2cb20 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e  _stmt*, int, con
2cb30 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
2cb40 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
2cb50 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2cb60 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2cb70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2cb80 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69   int, const sqli
2cb90 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
2cba0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2cbb0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2cbc0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2cbd0 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
2cbe0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2cbf0 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
2cc00 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54  ameters.**.** ^T
2cc10 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
2cc20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
2cc30 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
2cc40 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
2cc50 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
2cc60 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
2cc70 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
2cc80 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
2cc90 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
2cca0 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
2ccb0 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
2ccc0 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
2ccd0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
2cce0 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
2ccf0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2cd00 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
2cd10 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
2cd20 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
2cd30 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
2cd40 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
2cd50 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
2cd60 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
2cd70 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
2cd80 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
2cd90 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
2cda0 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
2cdb0 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
2cdc0 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
2cdd0 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
2cde0 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
2cdf0 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
2ce00 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
2ce10 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
2ce20 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
2ce30 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2ce40 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2ce50 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2ce60 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2ce70 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2ce80 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
2ce90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2cea0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2ceb0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2cec0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2ced0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2cee0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2cef0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cf00 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20   Name Of A Host 
2cf10 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20  Parameter.**.** 
2cf20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2cf30 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2cf40 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20  (P,N) interface 
2cf50 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
2cf60 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20  ame of the N-th 
2cf70 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
2cf80 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  in the [prepared
2cf90 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a   statement] P..*
2cfa0 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65  * ^(SQL paramete
2cfb0 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22  rs of the form "
2cfc0 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20  ?NNN" or ":AAA" 
2cfd0 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41  or "@AAA" or "$A
2cfe0 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61  AA".** have a na
2cff0 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65 20  me which is the 
2d000 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72  string "?NNN" or
2d010 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41   ":AAA" or "@AAA
2d020 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72  " or "$AAA".** r
2d030 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
2d040 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
2d050 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20  the initial ":" 
2d060 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72  or "$" or "@" or
2d070 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75   "?".** is inclu
2d080 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  ded as part of t
2d090 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50  he name.)^.** ^P
2d0a0 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2d0b0 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75   form "?" withou
2d0c0 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e  t a following in
2d0d0 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61  teger have no na
2d0e0 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65  me.** and are re
2d0f0 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61  ferred to as "na
2d100 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e  meless" or "anon
2d110 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73  ymous parameters
2d120 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  "..**.** ^The fi
2d130 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65 74  rst host paramet
2d140 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
2d150 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a  of 1, not 0..**.
2d160 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75 65  ** ^If the value
2d170 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e   N is out of ran
2d180 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d 74  ge or if the N-t
2d190 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
2d1a0 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e  * nameless, then
2d1b0 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e 65   NULL is returne
2d1c0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  d.  ^The returne
2d1d0 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61  d string is.** a
2d1e0 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20 65  lways in UTF-8 e
2d1f0 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66 20  ncoding even if 
2d200 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  the named parame
2d210 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69  ter was.** origi
2d220 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64 20  nally specified 
2d230 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73 71  as UTF-16 in [sq
2d240 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
2d250 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2d260 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2d270 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2d280 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2d290 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2d2a0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2d2b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2d2c0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2d2d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2d2e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2d2f0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2d300 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2d310 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2d320 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74  meter_name(sqlit
2d330 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a  e3_stmt*, int);.
2d340 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d350 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72 61   Index Of A Para
2d360 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69 76  meter With A Giv
2d370 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52  en Name.**.** ^R
2d380 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78 20  eturn the index 
2d390 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d 65  of an SQL parame
2d3a0 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e 61  ter given its na
2d3b0 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64  me.  ^The.** ind
2d3c0 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  ex value returne
2d3d0 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66 6f  d is suitable fo
2d3e0 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65 63  r use as the sec
2d3f0 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ond.** parameter
2d400 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e   to [sqlite3_bin
2d410 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2d420 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f  ind()].  ^A zero
2d430 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2d440 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70  if no matching p
2d450 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75 6e  arameter is foun
2d460 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74  d.  ^The paramet
2d470 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20  er.** name must 
2d480 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46 2d  be given in UTF-
2d490 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 72  8 even if the or
2d4a0 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
2d4b0 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65 64  .** was prepared
2d4c0 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65 78   from UTF-16 tex
2d4d0 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
2d4e0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
2d4f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2d500 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2d510 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2d520 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2d530 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2d540 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a  _count()], and.*
2d550 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2d560 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2d570 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2d580 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2d590 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2d5a0 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ex(sqlite3_stmt*
2d5b0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
2d5c0 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ame);../*.** CAP
2d5d0 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c  I3REF: Reset All
2d5e0 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50   Bindings On A P
2d5f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2d600 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72  t.**.** ^Contrar
2d610 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69  y to the intuiti
2d620 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c  on of many, [sql
2d630 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f  ite3_reset()] do
2d640 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20  es not reset.** 
2d650 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2d660 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67  d_blob | binding
2d670 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  s] on a [prepare
2d680 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2d690 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69   ^Use this routi
2d6a0 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20  ne to reset all 
2d6b0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
2d6c0 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49  to NULL..*/.SQLI
2d6d0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2d6e0 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67  e3_clear_binding
2d6f0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  s(sqlite3_stmt*)
2d700 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2d710 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c  F: Number Of Col
2d720 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c 74  umns In A Result
2d730 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75   Set.**.** ^Retu
2d740 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  rn the number of
2d750 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2d760 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75 72  result set retur
2d770 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70  ned by the.** [p
2d780 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d790 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  t]. ^This routin
2d7a0 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 70  e returns 0 if p
2d7b0 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a  Stmt is an SQL.*
2d7c0 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  * statement that
2d7d0 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72 6e   does not return
2d7e0 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d 70   data (for examp
2d7f0 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e  le an [UPDATE]).
2d800 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2d810 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63   [sqlite3_data_c
2d820 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
2d830 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2d840 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73  3_column_count(s
2d850 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2d860 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2d870 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d  3REF: Column Nam
2d880 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53  es In A Result S
2d890 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  et.**.** ^These 
2d8a0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
2d8b0 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e 65  the name assigne
2d8c0 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c 61  d to a particula
2d8d0 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74  r column.** in t
2d8e0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2d8f0 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74   a [SELECT] stat
2d900 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c  ement.  ^The sql
2d910 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
2d920 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
2d930 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2d940 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
2d950 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
2d960 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74  ing.** and sqlit
2d970 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36  e3_column_name16
2d980 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
2d990 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74  nter to a zero-t
2d9a0 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
2d9b0 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68  -16 string.  ^Th
2d9c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2d9d0 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61 72  r is the [prepar
2d9e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2d9f0 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73   that implements
2da00 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
2da10 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65  atement. ^The se
2da20 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
2da30 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  s the.** column 
2da40 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c 65  number.  ^The le
2da50 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73  ftmost column is
2da60 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a   number 0..**.**
2da70 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2da80 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69 73  tring pointer is
2da90 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69 74   valid until eit
2daa0 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72 65  her the [prepare
2dab0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2dac0 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79 20  is destroyed by 
2dad0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2dae0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2daf0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2db00 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2db10 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2db20 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2db30 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2db40 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2db50 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2db60 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c 20  l the next call 
2db70 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  to.** sqlite3_co
2db80 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73  lumn_name() or s
2db90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2dba0 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73 61  me16() on the sa
2dbb0 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a  me column..**.**
2dbc0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
2dbd0 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72 69  loc() fails duri
2dbe0 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69 6e  ng the processin
2dbf0 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75 74  g of either rout
2dc00 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d  ine.** (for exam
2dc10 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f 6e  ple during a con
2dc20 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46  version from UTF
2dc30 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74 68  -8 to UTF-16) th
2dc40 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69  en a.** NULL poi
2dc50 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
2dc60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2dc70 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63 6f  e of a result co
2dc80 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c 75  lumn is the valu
2dc90 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63 6c  e of the "AS" cl
2dca0 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74  ause for.** that
2dcb0 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72   column, if ther
2dcc0 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75 73  e is an AS claus
2dcd0 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20  e.  If there is 
2dce0 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20  no AS clause.** 
2dcf0 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  then the name of
2dd00 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75   the column is u
2dd10 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20 6d  nspecified and m
2dd20 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a  ay change from.*
2dd30 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f 66  * one release of
2dd40 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 6e   SQLite to the n
2dd50 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ext..*/.SQLITE_A
2dd60 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2dd70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2dd80 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2dd90 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45  , int N);.SQLITE
2dda0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2ddb0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ddc0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2ddd0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
2dde0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2ddf0 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
2de00 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2de10 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2de20 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
2de30 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
2de40 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
2de50 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
2de60 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
2de70 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
2de80 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
2de90 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
2dea0 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
2deb0 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
2dec0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2ded0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
2dee0 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
2def0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
2df00 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
2df10 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2df20 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
2df30 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
2df40 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
2df50 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
2df60 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2df70 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
2df80 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
2df90 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
2dfa0 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
2dfb0 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
2dfc0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2dfd0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
2dfe0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2dff0 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
2e000 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2e010 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2e020 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2e030 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2e040 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2e050 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2e060 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2e070 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2e080 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2e090 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2e0a0 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2e0b0 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
2e0c0 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
2e0d0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
2e0e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2e0f0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
2e100 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
2e110 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
2e120 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
2e130 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
2e140 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
2e150 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2e160 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2e170 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
2e180 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2e190 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2e1a0 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2e1b0 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
2e1c0 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
2e1d0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
2e1e0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
2e1f0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
2e200 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2e210 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
2e220 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
2e230 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
2e240 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2e250 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
2e260 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
2e270 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
2e280 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
2e290 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
2e2a0 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
2e2b0 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
2e2c0 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
2e2d0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2e2e0 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
2e2f0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
2e300 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
2e310 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2e320 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
2e330 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
2e340 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
2e350 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2e360 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
2e370 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
2e380 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
2e390 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
2e3a0 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
2e3b0 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
2e3c0 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
2e3d0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
2e3e0 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
2e3f0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
2e400 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
2e410 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
2e420 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
2e430 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
2e440 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
2e450 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
2e460 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2e470 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2e480 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2e490 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2e4a0 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2e4b0 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2e4c0 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
2e4d0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2e4e0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2e4f0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
2e500 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
2e510 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
2e520 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
2e530 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
2e540 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2e550 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
2e560 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2e570 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2e580 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2e590 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
2e5a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2e5b0 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
2e5c0 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
2e5d0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
2e5e0 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
2e5f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2e600 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
2e610 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
2e620 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2e630 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2e640 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
2e650 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
2e660 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2e670 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69  tabase_name(sqli
2e680 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2e690 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2e6a0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2e6b0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
2e6c0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2e6d0 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2e6e0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2e6f0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2e700 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
2e710 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2e720 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2e730 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2e740 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31  lumn_table_name1
2e750 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2e760 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2e770 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
2e780 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67  ite3_column_orig
2e790 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  in_name(sqlite3_
2e7a0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2e7b0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2e7c0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2e7d0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2e7e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2e7f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2e800 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2e810 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2e820 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2e830 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
2e840 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
2e850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2e860 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
2e870 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
2e880 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
2e890 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2e8a0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
2e8b0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
2e8c0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
2e8d0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
2e8e0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
2e8f0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2e900 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
2e910 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
2e920 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
2e930 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2e940 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
2e950 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2e960 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
2e970 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2e980 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
2e990 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2e9a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
2e9b0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2e9c0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
2e9d0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
2e9e0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
2e9f0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
2ea00 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
2ea10 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
2ea20 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
2ea30 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
2ea40 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
2ea50 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
2ea60 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
2ea70 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
2ea80 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
2ea90 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
2eaa0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
2eab0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
2eac0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
2ead0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
2eae0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2eaf0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
2eb00 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
2eb10 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
2eb20 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2eb30 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
2eb40 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
2eb50 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
2eb60 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
2eb70 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
2eb80 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
2eb90 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
2eba0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
2ebb0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
2ebc0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
2ebd0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
2ebe0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
2ebf0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
2ec00 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
2ec10 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
2ec20 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
2ec30 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
2ec40 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
2ec50 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
2ec60 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
2ec70 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
2ec80 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
2ec90 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2eca0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2ecb0 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
2ecc0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2ecd0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2ece0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2ecf0 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33 5f  ltype16(sqlite3_
2ed00 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a  stmt*,int);../*.
2ed10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76 61  ** CAPI3REF: Eva
2ed20 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74 61  luate An SQL Sta
2ed30 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74  tement.**.** Aft
2ed40 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  er a [prepared s
2ed50 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62 65  tatement] has be
2ed60 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  en prepared usin
2ed70 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c  g either.** [sql
2ed80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2ed90 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2eda0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2edb0 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65 67  r one of the leg
2edc0 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2edd0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
2ede0 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  re()] or [sqlite
2edf0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c 20  3_prepare16()], 
2ee00 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  this function.**
2ee10 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
2ee20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
2ee30 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74 68  s to evaluate th
2ee40 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a  e statement..**.
2ee50 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20 6f  ** The details o
2ee60 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  f the behavior o
2ee70 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  f the sqlite3_st
2ee80 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20 64  ep() interface d
2ee90 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74  epend.** on whet
2eea0 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65 6e  her the statemen
2eeb0 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20 75  t was prepared u
2eec0 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20 22  sing the newer "
2eed0 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  v2" interface.**
2eee0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2eef0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
2ef00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2ef10 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65  2()] or the olde
2ef20 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  r legacy.** inte
2ef30 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f 70  rface [sqlite3_p
2ef40 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2ef50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2ef60 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f 66  ()].  The use of
2ef70 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22   the.** new "v2"
2ef80 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65   interface is re
2ef90 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65  commended for ne
2efa0 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 62  w applications b
2efb0 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  ut the legacy.**
2efc0 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
2efd0 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20 73  continue to be s
2efe0 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  upported..**.** 
2eff0 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69  ^In the legacy i
2f000 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72 65  nterface, the re
2f010 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20  turn value will 
2f020 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  be either [SQLIT
2f030 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c  E_BUSY],.** [SQL
2f040 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49  ITE_DONE], [SQLI
2f050 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45  TE_ROW], [SQLITE
2f060 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c  _ERROR], or [SQL
2f070 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20  ITE_MISUSE]..** 
2f080 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20 69  ^With the "v2" i
2f090 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f 66  nterface, any of
2f0a0 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73 75   the other [resu
2f0b0 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20  lt codes] or.** 
2f0c0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
2f0d0 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62 65   codes] might be
2f0e0 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65 6c   returned as wel
2f0f0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  l..**.** ^[SQLIT
2f100 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74 68  E_BUSY] means th
2f110 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20  at the database 
2f120 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62 6c  engine was unabl
2f130 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68 65  e to acquire the
2f140 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f 63  .** database loc
2f150 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20 64  ks it needs to d
2f160 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20  o its job.  ^If 
2f170 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2f180 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f   a [COMMIT].** o
2f190 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64 65  r occurs outside
2f1a0 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   of an explicit 
2f1b0 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
2f1c0 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79 20  n you can retry 
2f1d0 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  the.** statement
2f1e0 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65 6d  .  If the statem
2f1f0 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f  ent is not a [CO
2f200 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72 73  MMIT] and occurs
2f210 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78   within an.** ex
2f220 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
2f230 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f 75  on then you shou
2f240 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20  ld rollback the 
2f250 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f  transaction befo
2f260 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67  re.** continuing
2f270 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
2f280 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61  _DONE] means tha
2f290 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
2f2a0 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78 65  has finished exe
2f2b0 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73  cuting.** succes
2f2c0 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33  sfully.  sqlite3
2f2d0 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
2f2e0 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
2f2f0 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74 75  in on this virtu
2f300 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69  al.** machine wi
2f310 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c 6c  thout first call
2f320 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
2f330 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  et()] to reset t
2f340 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  he virtual.** ma
2f350 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69 74  chine back to it
2f360 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2e  s initial state.
2f370 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53  .**.** ^If the S
2f380 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65 69  QL statement bei
2f390 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74 75  ng executed retu
2f3a0 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74 68  rns any data, th
2f3b0 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a  en [SQLITE_ROW].
2f3c0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 65  ** is returned e
2f3d0 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20 72  ach time a new r
2f3e0 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72 65  ow of data is re
2f3f0 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73 69  ady for processi
2f400 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c  ng by the.** cal
2f410 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73 20  ler. The values 
2f420 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64 20  may be accessed 
2f430 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d  using the [colum
2f440 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2f450 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ns]..** sqlite3_
2f460 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65 64  step() is called
2f470 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69 65   again to retrie
2f480 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77 20  ve the next row 
2f490 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e  of data..**.** ^
2f4a0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d  [SQLITE_ERROR] m
2f4b0 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e 2d  eans that a run-
2f4c0 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63 68  time error (such
2f4d0 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   as a constraint
2f4e0 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68  .** violation) h
2f4f0 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73 71  as occurred.  sq
2f500 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2f510 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2f520 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68  d again on.** th
2f530 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72  e VM. More infor
2f540 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f  mation may be fo
2f550 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  und by calling [
2f560 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
2f570 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2f580 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2f590 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66 69  , a more specifi
2f5a0 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66 6f  c error code (fo
2f5b0 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53  r example,.** [S
2f5c0 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d  QLITE_INTERRUPT]
2f5d0 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41  , [SQLITE_SCHEMA
2f5e0 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55  ], [SQLITE_CORRU
2f5f0 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74  PT], and so fort
2f600 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74  h).** can be obt
2f610 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e 67  ained by calling
2f620 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f630 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72  )] on the.** [pr
2f640 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f650 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32 22  ].  ^In the "v2"
2f660 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74   interface,.** t
2f670 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2f680 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20 72   error code is r
2f690 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2f6a0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2f6b0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54  ()..**.** [SQLIT
2f6c0 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73 20  E_MISUSE] means 
2f6d0 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72 6f  that the this ro
2f6e0 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65 64  utine was called
2f6f0 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c 79   inappropriately
2f700 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74 20  ..** Perhaps it 
2f710 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  was called on a 
2f720 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f730 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a  ent] that has.**
2f740 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b 73   already been [s
2f750 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2f760 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20  | finalized] or 
2f770 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64 0a  on one that had.
2f780 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  ** previously re
2f790 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45  turned [SQLITE_E
2f7a0 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45  RROR] or [SQLITE
2f7b0 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63  _DONE].  Or it c
2f7c0 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20 63  ould.** be the c
2f7d0 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61 6d  ase that the sam
2f7e0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
2f7f0 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 75  ction is being u
2f800 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a  sed by two or.**
2f810 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61 74   more threads at
2f820 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74   the same moment
2f830 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20   in time..**.** 
2f840 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73  For all versions
2f850 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74 6f   of SQLite up to
2f860 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20 33   and including 3
2f870 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20  .6.23.1, a call 
2f880 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  to.** [sqlite3_r
2f890 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71 75  eset()] was requ
2f8a0 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69 74  ired after sqlit
2f8b0 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72 6e  e3_step() return
2f8c0 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f  ed anything.** o
2f8d0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2f8e0 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e  E_ROW] before an
2f8f0 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  y subsequent inv
2f900 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71  ocation of.** sq
2f910 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 46  lite3_step().  F
2f920 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74 20  ailure to reset 
2f930 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
2f940 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a  tement using .**
2f950 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2f960 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74 20  )] would result 
2f970 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  in an [SQLITE_MI
2f980 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72 6f  SUSE] return fro
2f990 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  m.** sqlite3_ste
2f9a0 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72 20  p().  But after 
2f9b0 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31  version 3.6.23.1
2f9c0 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  , sqlite3_step()
2f9d0 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e   began.** callin
2f9e0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2f9f0 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ()] automaticall
2fa00 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75 6d  y in this circum
2fa10 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a  stance rather.**
2fa20 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67 20   than returning 
2fa30 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2fa40 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63 6f    This is not co
2fa50 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70 61  nsidered a compa
2fa60 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61  tibility.** brea
2fa70 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61 70  k because any ap
2fa80 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20 65  plication that e
2fa90 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e 20  ver receives an 
2faa0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65 72  SQLITE_MISUSE er
2fab0 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e  ror.** is broken
2fac0 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   by definition. 
2fad0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   The [SQLITE_OMI
2fae0 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d  T_AUTORESET] com
2faf0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
2fb00 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
2fb10 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20 6c  to restore the l
2fb20 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e 0a  egacy behavior..
2fb30 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49  **.** <b>Goofy I
2fb40 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a 3c  nterface Alert:<
2fb50 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61 63  /b> In the legac
2fb60 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  y interface, the
2fb70 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 0a   sqlite3_step().
2fb80 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72 65  ** API always re
2fb90 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63 20  turns a generic 
2fba0 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c  error code, [SQL
2fbb0 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c  ITE_ERROR], foll
2fbc0 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72  owing any.** err
2fbd0 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  or other than [S
2fbe0 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64 20  QLITE_BUSY] and 
2fbf0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2fc00 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a    You must call.
2fc10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2fc20 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
2fc30 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20  _finalize()] in 
2fc40 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e  order to find on
2fc50 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65 63  e of the.** spec
2fc60 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2fc70 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20 64  s] that better d
2fc80 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
2fc90 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20  or..** We admit 
2fca0 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20 67  that this is a g
2fcb0 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54 68  oofy design.  Th
2fcc0 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62 65  e problem has be
2fcd0 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74 68  en fixed.** with
2fce0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2fcf0 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72 65  ace.  If you pre
2fd00 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72  pare all of your
2fd10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
2fd20 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72 20  ** using either 
2fd30 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2fd40 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  _v2()] or [sqlit
2fd50 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2fd60 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66  )] instead.** of
2fd70 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71 6c   the legacy [sql
2fd80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2fd90 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2fda0 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72 66  pare16()] interf
2fdb0 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  aces,.** then th
2fdc0 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20  e more specific 
2fdd0 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61 72  [error codes] ar
2fde0 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65 63  e returned direc
2fdf0 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  tly.** by sqlite
2fe00 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20 75  3_step().  The u
2fe10 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20 69  se of the "v2" i
2fe20 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f  nterface is reco
2fe30 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49  mmended..*/.SQLI
2fe40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2fe50 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f  e3_step(sqlite3_
2fe60 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2fe70 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2fe80 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20  of columns in a 
2fe90 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a  result set.**.**
2fea0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2feb0 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65  ta_count(P) inte
2fec0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
2fed0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2fee0 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75  mns in the.** cu
2fef0 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65  rrent row of the
2ff00 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b   result set of [
2ff10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2ff20 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72  nt] P..** ^If pr
2ff30 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2ff40 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65   P does not have
2ff50 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74   results ready t
2ff60 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61  o return.** (via
2ff70 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73   calls to the [s
2ff80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
2ff90 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t | sqlite3_colu
2ffa0 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e  mn_*()] of.** in
2ffb0 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73  terfaces) then s
2ffc0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2ffd0 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a  t(P) returns 0..
2ffe0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2fff0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f  data_count(P) ro
30000 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72  utine also retur
30010 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e  ns 0 if P is a N
30020 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20  ULL pointer..** 
30030 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
30040 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
30050 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
30060 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c  the previous cal
30070 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
30080 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
30090 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  ed [SQLITE_DONE]
300a0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
300b0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a  data_count(P).**
300c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e   will return non
300d0 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75  -zero if previou
300e0 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  s call to [sqlit
300f0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
30100 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rned.** [SQLITE_
30110 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20  ROW], except in 
30120 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20  the case of the 
30130 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e  [PRAGMA incremen
30140 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77  tal_vacuum].** w
30150 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72  here it always r
30160 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63  eturns zero sinc
30170 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74  e each step of t
30180 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a  hat multi-step.*
30190 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73  * pragma returns
301a0 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61   0 columns of da
301b0 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ta..**.** See al
301c0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  so: [sqlite3_col
301d0 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  umn_count()].*/.
301e0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
301f0 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
30200 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
30210 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
30220 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d 65  API3REF: Fundame
30230 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a 2a  ntal Datatypes.*
30240 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
30250 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28  TE_TEXT.**.** ^(
30260 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20 53  Every value in S
30270 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f 66  QLite has one of
30280 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74 61   five fundamenta
30290 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a  l datatypes:.**.
302a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
302b0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
302c0 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34  teger.** <li> 64
302d0 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74 69  -bit IEEE floati
302e0 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a  ng point number.
302f0 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a  ** <li> string.*
30300 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c  * <li> BLOB.** <
30310 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c  li> NULL.** </ul
30320 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  >)^.**.** These 
30330 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63 6f  constants are co
30340 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66 20  des for each of 
30350 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a  those types..**.
30360 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  ** Note that the
30370 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e   SQLITE_TEXT con
30380 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20 75  stant was also u
30390 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76 65  sed in SQLite ve
303a0 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61  rsion 2.** for a
303b0 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66 66   completely diff
303c0 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20  erent meaning.  
303d0 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c 69  Software that li
303e0 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74 68  nks against both
303f0 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69  .** SQLite versi
30400 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65 20  on 2 and SQLite 
30410 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64  version 3 should
30420 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45 58   use SQLITE3_TEX
30430 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45  T, not.** SQLITE
30440 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e  _TEXT..*/.#defin
30450 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52  e SQLITE_INTEGER
30460 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
30470 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23 64  TE_FLOAT    2.#d
30480 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f  efine SQLITE_BLO
30490 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20  B     4.#define 
304a0 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20  SQLITE_NULL     
304b0 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  5.#ifdef SQLITE_
304c0 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51 4c  TEXT.# undef SQL
304d0 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23  ITE_TEXT.#else.#
304e0 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54   define SQLITE_T
304f0 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69 66  EXT     3.#endif
30500 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 33  .#define SQLITE3
30510 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a  _TEXT     3../*.
30520 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
30530 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d 20  ult Values From 
30540 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f  A Query.** KEYWO
30550 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63  RDS: {column acc
30560 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a  ess functions}.*
30570 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
30580 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72 65  nes form the "re
30590 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72 66  sult set" interf
305a0 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ace..**.** ^Thes
305b0 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
305c0 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  n information ab
305d0 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c  out a single col
305e0 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65  umn of the curre
305f0 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77  nt.** result row
30600 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e 49   of a query.  ^I
30610 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68 65  n every case the
30620 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
30630 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  is a pointer.** 
30640 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  to the [prepared
30650 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74   statement] that
30660 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75 61   is being evalua
30670 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65  ted (the [sqlite
30680 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74  3_stmt*].** that
30690 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66 72   was returned fr
306a0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  om [sqlite3_prep
306b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  are_v2()] or one
306c0 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74 73   of its variants
306d0 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65 63  ).** and the sec
306e0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
306f0 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  the index of the
30700 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63   column for whic
30710 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
30720 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72   should be retur
30730 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ned. ^The leftmo
30740 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  st column of the
30750 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73 20   result set has 
30760 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20  the index 0..** 
30770 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63  ^The number of c
30780 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65  olumns in the re
30790 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74 65  sult can be dete
307a0 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20  rmined using.** 
307b0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
307c0 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  count()]..**.** 
307d0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
307e0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 75  ment does not cu
307f0 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f  rrently point to
30800 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72   a valid row, or
30810 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d   if the.** colum
30820 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  n index is out o
30830 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65 73  f range, the res
30840 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
30850 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  ..** These routi
30860 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  nes may only be 
30870 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65 20  called when the 
30880 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
30890 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
308a0 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74 75  step()] has retu
308b0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57  rned [SQLITE_ROW
308c0 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a  ] and neither.**
308d0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
308e0 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f  )] nor [sqlite3_
308f0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76 65  finalize()] have
30900 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75 62   been called sub
30910 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66  sequently..** If
30920 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
30930 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
30940 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
30950 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
30960 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
30970 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b 73  e()] or after [s
30980 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
30990 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73  as returned.** s
309a0 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
309b0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
309c0 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  , the results ar
309d0 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  e undefined..** 
309e0 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  If [sqlite3_step
309f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
30a00 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
30a10 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
30a20 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20 66  .** are called f
30a30 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74 20  rom a different 
30a40 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e 79  thread while any
30a50 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
30a60 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e  es.** are pendin
30a70 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75  g, then the resu
30a80 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
30a90 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
30aa0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
30ab0 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  e() routine retu
30ac0 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  rns the.** [SQLI
30ad0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
30ae0 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72 20  atype code] for 
30af0 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74 61  the initial data
30b00 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20   type.** of the 
30b10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20  result column.  
30b20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76 61  ^The returned va
30b30 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53  lue is one of [S
30b40 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a  QLITE_INTEGER],.
30b50 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54  ** [SQLITE_FLOAT
30b60 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d  ], [SQLITE_TEXT]
30b70 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c  , [SQLITE_BLOB],
30b80 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c   or [SQLITE_NULL
30b90 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a  ].  The value.**
30ba0 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
30bb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
30bc0 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69  () is only meani
30bd0 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70 65  ngful if no type
30be0 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  .** conversions 
30bf0 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61 73  have occurred as
30c00 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f 77   described below
30c10 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65 20  .  After a type 
30c20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74  conversion,.** t
30c30 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
30c40 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
30c50 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75 6e  umn_type() is un
30c60 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72 65  defined.  Future
30c70 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  .** versions of 
30c80 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e 67  SQLite may chang
30c90 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  e the behavior o
30ca0 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  f sqlite3_column
30cb0 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f  _type().** follo
30cc0 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e 76  wing a type conv
30cd0 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ersion..**.** ^I
30ce0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
30cf0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20  a BLOB or UTF-8 
30d00 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
30d10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30d20 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ytes().** routin
30d30 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
30d40 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
30d50 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74   that BLOB or st
30d60 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
30d70 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54 46   result is a UTF
30d80 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65 6e  -16 string, then
30d90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30da0 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74 73  bytes() converts
30db0 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74  .** the string t
30dc0 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65 6e  o UTF-8 and then
30dd0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
30de0 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
30df0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
30e00 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
30e10 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
30e20 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 75  column_bytes() u
30e30 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
30e40 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
30e50 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
30e60 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74 72  e to a UTF-8 str
30e70 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
30e80 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
30e90 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
30ea0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
30eb0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
30ec0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
30ed0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72 65  olumn_bytes() re
30ee0 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
30ef0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
30f00 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
30f10 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65 6e  F-16 string then
30f20 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
30f30 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a  umn_bytes16().**
30f40 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
30f50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
30f60 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
30f70 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
30f80 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
30f90 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  s a UTF-8 string
30fa0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
30fb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
30fc0 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20  converts.** the 
30fd0 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31 36  string to UTF-16
30fe0 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e   and then return
30ff0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
31000 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  bytes..** ^If th
31010 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75  e result is a nu
31020 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e  meric value then
31030 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31040 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a 2a  bytes16() uses.*
31050 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
31060 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
31070 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
31080 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  a UTF-16 string 
31090 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
310a0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
310b0 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
310c0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
310d0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
310e0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
310f0 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74 75  n_bytes16() retu
31100 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20  rns zero..**.** 
31110 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
31120 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
31130 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d  _column_bytes()]
31140 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   and .** [sqlite
31150 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
31160 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75  ()] do not inclu
31170 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  de the zero term
31180 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20 65  inators at the e
31190 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74 72  nd.** of the str
311a0 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69  ing.  ^For clari
311b0 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20 72  ty: the values r
311c0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
311d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
311e0 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  tes()] and [sqli
311f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31200 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e 75  16()] are the nu
31210 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73  mber of.** bytes
31220 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c 20   in the string, 
31230 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
31240 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a  f characters..**
31250 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65 74  .** ^Strings ret
31260 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
31270 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61  _column_text() a
31280 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
31290 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65  n_text16(),.** e
312a0 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67  ven empty string
312b0 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a 65  s, are always ze
312c0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ro-terminated.  
312d0 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76  ^The return.** v
312e0 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65  alue from sqlite
312f0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
31300 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74  for a zero-lengt
31310 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c  h BLOB is a NULL
31320 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
31330 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74 75  ^The object retu
31340 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
31350 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
31360 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f   is an.** [unpro
31370 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
31380 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41  alue] object.  A
31390 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71  n unprotected sq
313a0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
313b0 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62  ct.** may only b
313c0 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71 6c  e used with [sql
313d0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
313e0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
313f0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e  result_value()].
31400 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70 72  .** If the [unpr
31410 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
31420 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72 65  value] object re
31430 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
31440 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
31450 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  ue()] is used in
31460 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c 20   any other way, 
31470 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a  including calls.
31480 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  ** to routines l
31490 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  ike [sqlite3_val
314a0 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69  ue_int()], [sqli
314b0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
314c0 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  ],.** or [sqlite
314d0 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
314e0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
314f0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
31500 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
31510 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20 74  utines attempt t
31520 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61  o convert the va
31530 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f 70  lue where approp
31540 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20  riate.  ^For.** 
31550 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65 20  example, if the 
31560 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
31570 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54  ntation is FLOAT
31580 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73 75   and a text resu
31590 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73 74  lt.** is request
315a0 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  ed, [sqlite3_snp
315b0 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65 64  rintf()] is used
315c0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70   internally to p
315d0 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f  erform the.** co
315e0 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74  nversion automat
315f0 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66  ically.  ^(The f
31600 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20 64  ollowing table d
31610 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76 65  etails the conve
31620 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61  rsions.** that a
31630 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a  re applied:.**.*
31640 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  * <blockquote>.*
31650 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
31660 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e  "1">.** <tr><th>
31670 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70   Internal<br>Typ
31680 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65 64  e <th> Requested
31690 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 43  <br>Type <th>  C
316a0 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20  onversion.**.** 
316b0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
316c0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
316d0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
316e0 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  0.** <tr><td>  N
316f0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  ULL    <td>  FLO
31700 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  AT    <td> Resul
31710 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e  t is 0.0.** <tr>
31720 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
31730 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
31740 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
31750 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
31760 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
31770 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
31780 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  > Result is NULL
31790 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e   pointer.** <tr>
317a0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
317b0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
317c0 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69  > Convert from i
317d0 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a  nteger to float.
317e0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
317f0 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58 54  GER  <td>   TEXT
31800 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72      <td> ASCII r
31810 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20  endering of the 
31820 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c  integer.** <tr><
31830 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
31840 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  >   BLOB    <td>
31850 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45 52   Same as INTEGER
31860 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
31870 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
31880 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
31890 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f  Convert from flo
318a0 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a  at to integer.**
318b0 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
318c0 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
318d0 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e    <td> ASCII ren
318e0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c  dering of the fl
318f0 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  oat.** <tr><td> 
31900 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
31910 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
31920 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54  e as FLOAT->TEXT
31930 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
31940 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  XT    <td> INTEG
31950 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  ER   <td> Use at
31960 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
31970 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
31980 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55 73  FLOAT    <td> Us
31990 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
319a0 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
319b0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
319c0 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
319d0 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
319e0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
319f0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20  <td> Convert to 
31a00 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74  TEXT then use at
31a10 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  oi().** <tr><td>
31a20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20    BLOB    <td>  
31a30 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
31a40 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74 68  nvert to TEXT th
31a50 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a  en use atof().**
31a60 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
31a70 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
31a80 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65 72    <td> Add a zer
31a90 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66 20  o terminator if 
31aa0 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c  needed.** </tabl
31ab0 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f  e>.** </blockquo
31ac0 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  te>)^.**.** The 
31ad0 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65  table above make
31ae0 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20 73  s reference to s
31af0 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
31b00 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69  y functions atoi
31b10 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29  ().** and atof()
31b20 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e  .  SQLite does n
31b30 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74 68  ot really use th
31b40 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  ese functions.  
31b50 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77  It has its.** ow
31b60 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e 74  n equivalent int
31b70 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20  ernal routines. 
31b80 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64 20   The atoi() and 
31b90 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72 65  atof() names are
31ba0 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65 20  .** used in the 
31bb0 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69 74  table for brevit
31bc0 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74 68  y and because th
31bd0 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72 20  ey are familiar 
31be0 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f  to most.** C pro
31bf0 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  grammers..**.** 
31c00 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20 74  Note that when t
31c10 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20  ype conversions 
31c20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73 20  occur, pointers 
31c30 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69 6f  returned by prio
31c40 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  r.** calls to sq
31c50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
31c60 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  b(), sqlite3_col
31c70 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f  umn_text(), and/
31c80 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  or.** sqlite3_co
31c90 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d 61  lumn_text16() ma
31ca0 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  y be invalidated
31cb0 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65 72  ..** Type conver
31cc0 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65  sions and pointe
31cd0 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20  r invalidations 
31ce0 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69  might occur.** i
31cf0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
31d00 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  cases:.**.** <ul
31d10 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
31d20 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
31d30 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69   a BLOB and sqli
31d40 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
31d50 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
31d60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31d70 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
31d80 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   A zero-terminat
31d90 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20  or might.**     
31da0 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64 65   need to be adde
31db0 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67 2e  d to the string.
31dc0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  </li>.** <li> Th
31dd0 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e  e initial conten
31de0 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74 20  t is UTF-8 text 
31df0 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
31e00 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72 0a  mn_bytes16() or.
31e10 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
31e20 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
31e30 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20  is called.  The 
31e40 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20  content must be 
31e50 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20  converted.**    
31e60 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69    to UTF-16.</li
31e70 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
31e80 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
31e90 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e 64   UTF-16 text and
31ea0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31eb0 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20  bytes() or.**   
31ec0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
31ed0 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c 6c  n_text() is call
31ee0 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e 74  ed.  The content
31ef0 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
31f00 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55 54  ed.**      to UT
31f10 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  F-8.</li>.** </u
31f20 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72  l>.**.** ^Conver
31f30 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55 54  sions between UT
31f40 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d 31  F-16be and UTF-1
31f50 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20 64  6le are always d
31f60 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e 64  one in place and
31f70 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c   do.** not inval
31f80 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70 6f  idate a prior po
31f90 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f 66  inter, though of
31fa0 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e 74   course the cont
31fb0 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66 65  ent of the buffe
31fc0 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70 72  r.** that the pr
31fd0 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66 65  ior pointer refe
31fe0 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76 65  rences will have
31ff0 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20   been modified. 
32000 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20   Other kinds.** 
32010 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72  of conversion ar
32020 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  e done in place 
32030 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73 69  when it is possi
32040 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d  ble, but sometim
32050 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e  es they.** are n
32060 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64 20  ot possible and 
32070 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20 70  in those cases p
32080 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61 72  rior pointers ar
32090 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
320a0 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74 20  *.** The safest 
320b0 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20 72  and easiest to r
320c0 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20 69  emember policy i
320d0 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73  s to invoke thes
320e0 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e  e routines.** in
320f0 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
32100 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a  owing ways:.**.*
32110 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73  * <ul>.**  <li>s
32120 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
32130 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79  xt() followed by
32140 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32150 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  bytes()</li>.** 
32160 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
32170 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f  umn_blob() follo
32180 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
32190 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
321a0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
321b0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
321c0 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73  () followed by s
321d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
321e0 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20  tes16()</li>.** 
321f0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f  </ul>.**.** In o
32200 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75 20  ther words, you 
32210 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69  should call sqli
32220 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
32230 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  ),.** sqlite3_co
32240 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20  lumn_blob(), or 
32250 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
32260 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74 6f  ext16() first to
32270 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75 6c   force the resul
32280 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64 65  t.** into the de
32290 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74 68  sired format, th
322a0 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  en invoke sqlite
322b0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
322c0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   or.** sqlite3_c
322d0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
322e0 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a 65  to find the size
322f0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e 20   of the result. 
32300 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   Do not mix call
32310 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  s.** to sqlite3_
32320 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
32330 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32340 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c 6c  blob() with call
32350 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  s to.** sqlite3_
32360 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
32370 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78  , and do not mix
32380 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
32390 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
323a0 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73 20  ).** with calls 
323b0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
323c0 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a  n_bytes()..**.**
323d0 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20 72   ^The pointers r
323e0 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c 69  eturned are vali
323f0 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20 63  d until a type c
32400 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73  onversion occurs
32410 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65 64   as.** described
32420 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c   above, or until
32430 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
32440 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
32450 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
32460 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
32470 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54  ] is called.  ^T
32480 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  he memory space 
32490 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74 72  used to hold str
324a0 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42  ings.** and BLOB
324b0 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f 6d  s is freed autom
324c0 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62  atically.  Do <b
324d0 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74 68  >not</b> pass th
324e0 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
324f0 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ned.** [sqlite3_
32500 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20  column_blob()], 
32510 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
32520 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e  text()], etc. in
32530 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
32540 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ree()]..**.** ^(
32550 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  If a memory allo
32560 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
32570 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20 65  urs during the e
32580 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79  valuation of any
32590 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f 75  .** of these rou
325a0 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c 74  tines, a default
325b0 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72 6e   value is return
325c0 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  ed.  The default
325d0 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74   value.** is eit
325e0 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72 20  her the integer 
325f0 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67 20  0, the floating 
32600 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30  point number 0.0
32610 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  , or a NULL.** p
32620 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71 75  ointer.  Subsequ
32630 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  ent calls to [sq
32640 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d  lite3_errcode()]
32650 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20   will return.** 
32660 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29  [SQLITE_NOMEM].)
32670 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
32680 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
32690 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
326a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
326b0 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
326c0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
326d0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
326e0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
326f0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
32700 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
32710 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73 71  olumn_bytes16(sq
32720 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
32730 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
32740 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  PI double sqlite
32750 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
32760 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
32770 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45  nt iCol);.SQLITE
32780 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
32790 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69  _column_int(sqli
327a0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
327b0 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
327c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
327d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
327e0 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t64(sqlite3_stmt
327f0 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
32800 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
32810 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
32820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32830 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
32840 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
32850 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
32860 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
32870 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
32880 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
32890 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
328a0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
328b0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
328c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
328d0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
328e0 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65  e3_value *sqlite
328f0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73  3_column_value(s
32900 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32910 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t iCol);../*.** 
32920 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f  CAPI3REF: Destro
32930 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  y A Prepared Sta
32940 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
32950 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32960 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63  _finalize() func
32970 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
32980 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70  o delete a [prep
32990 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
329a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
329b0 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
329c0 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d  on of the statem
329d0 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  ent encountered 
329e0 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20  no errors.** or 
329f0 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
32a00 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20 65   is never been e
32a10 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20 73  valuated, then s
32a20 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
32a30 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c  ) returns.** SQL
32a40 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65  ITE_OK.  ^If the
32a50 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
32a60 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74 65  luation of state
32a70 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20 74  ment S failed, t
32a80 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  hen.** sqlite3_f
32a90 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75 72  inalize(S) retur
32aa0 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69 61  ns the appropria
32ab0 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  te [error code] 
32ac0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
32ad0 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a  error code]..**.
32ae0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
32af0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75 74  finalize(S) rout
32b00 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ine can be calle
32b10 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 64  d at any point d
32b20 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66  uring.** the lif
32b30 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65 70  e cycle of [prep
32b40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
32b50 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74 61  S:.** before sta
32b60 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65 72  tement S is ever
32b70 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74 65   evaluated, afte
32b80 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  r.** one or more
32b90 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
32ba0 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72 20  e3_reset()], or 
32bb0 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a  after any call.*
32bc0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  * to [sqlite3_st
32bd0 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73 73  ep()] regardless
32be0 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e   of whether or n
32bf0 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ot the statement
32c00 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65   has.** complete
32c10 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a  d execution..**.
32c20 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c  ** ^Invoking sql
32c30 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20  ite3_finalize() 
32c40 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  on a NULL pointe
32c50 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20  r is a harmless 
32c60 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  no-op..**.** The
32c70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
32c80 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72 79  t finalize every
32c90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
32ca0 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20 74  ment] in order t
32cb0 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75  o avoid.** resou
32cc0 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20 69  rce leaks.  It i
32cd0 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72 72  s a grievous err
32ce0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
32cf0 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f  cation to try to
32d00 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61 72   use.** a prepar
32d10 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74  ed statement aft
32d20 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 66  er it has been f
32d30 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75  inalized.  Any u
32d40 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65 64  se of a prepared
32d50 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 66  .** statement af
32d60 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
32d70 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72 65  finalized can re
32d80 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65  sult in undefine
32d90 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72  d and.** undesir
32da0 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73 75  able behavior su
32db0 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73 20  ch as segfaults 
32dc0 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70 74  and heap corrupt
32dd0 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
32de0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 66  PI int sqlite3_f
32df0 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f  inalize(sqlite3_
32e00 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
32e10 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
32e20 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20  eset A Prepared 
32e30 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
32e40 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
32e50 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74  e3_reset() funct
32e60 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
32e70 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72   reset a [prepar
32e80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
32e90 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20   object back to 
32ea0 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74  its initial stat
32eb0 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72  e, ready to be r
32ec0 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e  e-executed..** ^
32ed0 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  Any SQL statemen
32ee0 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74  t variables that
32ef0 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e   had values boun
32f00 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a  d to them using.
32f10 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** the [sqlite3_
32f20 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  bind_blob | sqli
32f30 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49  te3_bind_*() API
32f40 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76  ] retain their v
32f50 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73  alues..** Use [s
32f60 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
32f70 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65  dings()] to rese
32f80 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a  t the bindings..
32f90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
32fa0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
32fb0 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74  terface resets t
32fc0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
32fd0 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63  tement] S.** bac
32fe0 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  k to the beginni
32ff0 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61  ng of its progra
33000 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  m..**.** ^If the
33010 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
33020 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
33030 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a  ep(S)] for the.*
33040 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
33050 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65  ement] S returne
33060 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f  d [SQLITE_ROW] o
33070 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  r [SQLITE_DONE],
33080 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74  .** or if [sqlit
33090 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20  e3_step(S)] has 
330a0 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65  never before bee
330b0 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a  n called on S,.*
330c0 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  * then [sqlite3_
330d0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
330e0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  s [SQLITE_OK]..*
330f0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  *.** ^If the mos
33100 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
33110 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
33120 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70  )] for the.** [p
33130 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
33140 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61  t] S indicated a
33150 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a  n error, then.**
33160 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
33170 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61  S)] returns an a
33180 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
33190 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  r code]..**.** ^
331a0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  The [sqlite3_res
331b0 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65  et(S)] interface
331c0 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
331d0 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f   the values.** o
331e0 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62  f any [sqlite3_b
331f0 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67  ind_blob|binding
33200 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61  s] on the [prepa
33210 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
33220 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
33230 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65  int sqlite3_rese
33240 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  t(sqlite3_stmt *
33250 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
33260 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20  API3REF: Create 
33270 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20  Or Redefine SQL 
33280 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  Functions.** KEY
33290 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e  WORDS: {function
332a0 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
332b0 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  es}.** KEYWORDS:
332c0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
332d0 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
332e0 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  on}.** KEYWORDS:
332f0 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   {application-de
33300 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
33310 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ons}.**.** ^Thes
33320 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c  e functions (col
33330 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20  lectively known 
33340 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65  as "function cre
33350 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29  ation routines")
33360 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20  .** are used to 
33370 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  add SQL function
33380 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20  s or aggregates 
33390 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74  or to redefine t
333a0 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f  he behavior.** o
333b0 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66  f existing SQL f
333c0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
333d0 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c  egates.  The onl
333e0 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65  y differences be
333f0 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72  tween.** these r
33400 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20  outines are the 
33410 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78  text encoding ex
33420 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68  pected for.** th
33430 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
33440 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20  er (the name of 
33450 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69  the function bei
33460 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61  ng created).** a
33470 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20  nd the presence 
33480 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20  or absence of a 
33490 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62  destructor callb
334a0 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61  ack for.** the a
334b0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
334c0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
334d0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
334e0 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61  ter is the [data
334f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33500 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51   to which the SQ
33510 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  L.** function is
33520 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e   to be added.  ^
33530 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  If an applicatio
33540 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e  n uses more than
33550 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a   one database.**
33560 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e   connection then
33570 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
33580 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
33590 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64  ns must be added
335a0 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61  .** to each data
335b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
335c0 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  separately..**.*
335d0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  * ^The second pa
335e0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e  rameter is the n
335f0 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66  ame of the SQL f
33600 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72  unction to be cr
33610 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65  eated or.** rede
33620 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e  fined.  ^The len
33630 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20  gth of the name 
33640 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35  is limited to 25
33650 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46  5 bytes in a UTF
33660 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61  -8.** representa
33670 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20  tion, exclusive 
33680 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d  of the zero-term
33690 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74  inator.  ^Note t
336a0 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20  hat the name.** 
336b0 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20  length limit is 
336c0 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20  in UTF-8 bytes, 
336d0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e  not characters n
336e0 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e  or UTF-16 bytes.
336f0 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d    .** ^Any attem
33700 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66  pt to create a f
33710 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c  unction with a l
33720 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69  onger name.** wi
33730 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51  ll result in [SQ
33740 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69  LITE_MISUSE] bei
33750 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  ng returned..**.
33760 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  ** ^The third pa
33770 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a  rameter (nArg).*
33780 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  * is the number 
33790 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  of arguments tha
337a0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
337b0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
337c0 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68  te takes. ^If th
337d0 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  is parameter is 
337e0 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c  -1, then the SQL
337f0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
33800 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61  aggregate may ta
33810 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66  ke any number of
33820 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65   arguments betwe
33830 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d  en 0 and the lim
33840 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71  it.** set by [sq
33850 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51  lite3_limit]([SQ
33860 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
33870 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74  ION_ARG]).  If t
33880 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
33890 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68  meter is less th
338a0 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72  an -1 or greater
338b0 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74   than 127 then t
338c0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a  he behavior is.*
338d0 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
338e0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
338f0 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52  arameter, eTextR
33900 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68  ep, specifies wh
33910 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54  at.** [SQLITE_UT
33920 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69  F8 | text encodi
33930 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e  ng] this SQL fun
33940 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f  ction prefers fo
33950 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74  r.** its paramet
33960 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20  ers.  Every SQL 
33970 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
33980 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  ntation must be 
33990 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20  able to work.** 
339a0 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d  with UTF-8, UTF-
339b0 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62  16le, or UTF-16b
339c0 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70  e.  But some imp
339d0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79  lementations may
339e0 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69   be.** more effi
339f0 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65  cient with one e
33a00 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f  ncoding than ano
33a10 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69  ther.  ^An appli
33a20 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e  cation may.** in
33a30 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  voke sqlite3_cre
33a40 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f  ate_function() o
33a50 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
33a60 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75  _function16() mu
33a70 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20  ltiple.** times 
33a80 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75  with the same fu
33a90 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20  nction but with 
33aa0 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73  different values
33ab0 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a   of eTextRep..**
33ac0 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20   ^When multiple 
33ad0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
33ae0 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
33af0 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62  tion are availab
33b00 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69  le, SQLite.** wi
33b10 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20  ll pick the one 
33b20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68  that involves th
33b30 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f  e least amount o
33b40 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f  f data conversio
33b50 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69  n..** If there i
33b60 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  s only a single 
33b70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
33b80 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61  hich does not ca
33b90 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20  re what text.** 
33ba0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
33bb0 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74  , then the fourt
33bc0 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  h argument shoul
33bd0 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59  d be [SQLITE_ANY
33be0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66  ]..**.** ^(The f
33bf0 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  ifth parameter i
33c00 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70  s an arbitrary p
33c10 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70  ointer.  The imp
33c20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74  lementation of t
33c30 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63  he.** function c
33c40 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74  an gain access t
33c50 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75  o this pointer u
33c60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73  sing [sqlite3_us
33c70 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a  er_data()].)^.**
33c80 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20  .** ^The sixth, 
33c90 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68  seventh and eigh
33ca0 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78  th parameters, x
33cb0 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20  Func, xStep and 
33cc0 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70  xFinal, are.** p
33cd0 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e  ointers to C-lan
33ce0 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20  guage functions 
33cf0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
33d00 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
33d10 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e  or.** aggregate.
33d20 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66   ^A scalar SQL f
33d30 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73  unction requires
33d40 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69   an implementati
33d50 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a  on of the xFunc.
33d60 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79  ** callback only
33d70 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20  ; NULL pointers 
33d80 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61  must be passed a
33d90 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20  s the xStep and 
33da0 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65  xFinal.** parame
33db0 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67  ters. ^An aggreg
33dc0 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ate SQL function
33dd0 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70   requires an imp
33de0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78  lementation of x
33df0 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e  Step.** and xFin
33e00 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e  al and NULL poin
33e10 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73  ter must be pass
33e20 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54  ed for xFunc. ^T
33e30 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73  o delete an exis
33e40 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63  ting.** SQL func
33e50 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
33e60 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69  e, pass NULL poi
33e70 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68  nters for all th
33e80 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ree function.** 
33e90 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a  callbacks..**.**
33ea0 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20   ^(If the ninth 
33eb0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
33ec0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33ed0 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74  tion_v2() is not
33ee0 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69   NULL,.** then i
33ef0 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20  t is destructor 
33f00 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
33f10 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ion data pointer
33f20 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75  . .** The destru
33f30 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20  ctor is invoked 
33f40 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f  when the functio
33f50 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69  n is deleted, ei
33f60 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a  ther by being.**
33f70 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77   overloaded or w
33f80 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
33f90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
33fa0 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65  es.)^.** ^The de
33fb0 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f  structor is also
33fc0 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
33fd0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
33fe0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
33ff0 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a  on_v2() fails..*
34000 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74  * ^When the dest
34010 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
34020 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72  of the tenth par
34030 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65  ameter is invoke
34040 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73  d, it.** is pass
34050 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  ed a single argu
34060 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
34070 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c  copy of the appl
34080 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a  ication data .**
34090 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77   pointer which w
340a0 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72  as the fifth par
340b0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
340c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
340d0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49  n_v2()..**.** ^I
340e0 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  t is permitted t
340f0 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69  o register multi
34100 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
34110 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a  ons of the same.
34120 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74  ** functions wit
34130 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20  h the same name 
34140 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20  but with either 
34150 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72  differing number
34160 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  s of.** argument
34170 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70  s or differing p
34180 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
34190 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74  codings.  ^SQLit
341a0 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68  e will use.** th
341b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
341c0 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65   that most close
341d0 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77  ly matches the w
341e0 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a  ay in which the.
341f0 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
34200 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e  is used.  ^A fun
34210 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
34220 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d  tion with a non-
34230 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67  negative.** nArg
34240 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
34250 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61  better match tha
34260 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  n a function imp
34270 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68  lementation with
34280 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e  .** a negative n
34290 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  Arg.  ^A functio
342a0 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66  n where the pref
342b0 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
342c0 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74  ing.** matches t
342d0 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f  he database enco
342e0 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72  ding is a better
342f0 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61  .** match than a
34300 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
34310 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  the encoding is 
34320 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20  different.  .** 
34330 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72  ^A function wher
34340 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64  e the encoding d
34350 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74  ifference is bet
34360 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64  ween UTF16le and
34370 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61   UTF16be.** is a
34380 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68   closer match th
34390 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68  an a function wh
343a0 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67  ere the encoding
343b0 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a   difference is.*
343c0 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61  * between UTF8 a
343d0 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20  nd UTF16..**.** 
343e0 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69  ^Built-in functi
343f0 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c  ons may be overl
34400 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70  oaded by new app
34410 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
34420 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a   functions..**.*
34430 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  * ^An applicatio
34440 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34450 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  on is permitted 
34460 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a  to call other.**
34470 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
34480 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75  es.  However, su
34490 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f  ch calls must no
344a0 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64  t.** close the d
344b0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
344c0 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20  on nor finalize 
344d0 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65  or reset the pre
344e0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
344f0 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  nt in which the 
34500 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
34510 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
34520 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
34530 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
34540 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
34550 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
34560 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
34570 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
34580 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
34590 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
345a0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
345b0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
345c0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
345d0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
345e0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
345f0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
34600 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
34610 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
34620 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  text*).);.SQLITE
34630 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
34640 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
34650 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  16(.  sqlite3 *d
34660 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  b,.  const void 
34670 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
34680 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
34690 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
346a0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
346b0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
346c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
346d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
346e0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
346f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34700 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
34710 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
34720 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
34730 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51  _context*).);.SQ
34740 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
34750 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34760 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74  tion_v2(.  sqlit
34770 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
34780 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  char *zFunctionN
34790 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
347a0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
347b0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
347c0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
347d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
347e0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
347f0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
34800 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
34810 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
34820 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
34830 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
34840 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c  lite3_context*),
34850 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
34860 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a  y)(void*).);../*
34870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65  .** CAPI3REF: Te
34880 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a  xt Encodings.**.
34890 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
348a0 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72  t define integer
348b0 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70 72   codes that repr
348c0 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75  esent the variou
348d0 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69  s.** text encodi
348e0 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62 79  ngs supported by
348f0 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
34900 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20  ine SQLITE_UTF8 
34910 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
34920 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
34930 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65 66  LE        2.#def
34940 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
34950 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65 66  BE        3.#def
34960 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
34970 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20 2f            4    /
34980 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79 74  * Use native byt
34990 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69  e order */.#defi
349a0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20  ne SQLITE_ANY   
349b0 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a           5    /*
349c0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
349d0 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f  function only */
349e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
349f0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
34a00 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
34a10 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
34a20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
34a30 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63 61  API3REF: Depreca
34a40 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  ted Functions.**
34a50 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a   DEPRECATED.**.*
34a60 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  * These function
34a70 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74 65  s are [deprecate
34a80 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f  d].  In order to
34a90 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63   maintain.** bac
34aa0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
34ab0 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20  lity with older 
34ac0 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63  code, these func
34ad0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a  tions continue .
34ae0 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ** to be support
34af0 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65  ed.  However, ne
34b00 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  w applications s
34b10 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74  hould avoid.** t
34b20 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65 20  he use of these 
34b30 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68  functions.  To h
34b40 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65  elp encourage pe
34b50 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  ople to avoid.**
34b60 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e   using these fun
34b70 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e  ctions, we are n
34b80 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c  ot going to tell
34b90 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20 64   you what they d
34ba0 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  o..*/.#ifndef SQ
34bb0 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43  LITE_OMIT_DEPREC
34bc0 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49 20  ATED.SQLITE_API 
34bd0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
34be0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
34bf0 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
34c00 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
34c10 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
34c20 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
34c30 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72 65  t sqlite3_expire
34c40 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  d(sqlite3_stmt*)
34c50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
34c60 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
34c70 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e 73  nt sqlite3_trans
34c80 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  fer_bindings(sql
34c90 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69  ite3_stmt*, sqli
34ca0 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49  te3_stmt*);.SQLI
34cb0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
34cc0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
34cd0 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f  ite3_global_reco
34ce0 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  ver(void);.SQLIT
34cf0 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
34d00 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c  RECATED void sql
34d10 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65 61  ite3_thread_clea
34d20 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  nup(void);.SQLIT
34d30 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
34d40 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
34d50 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d  te3_memory_alarm
34d60 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73  (void(*)(void*,s
34d70 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74  qlite3_int64,int
34d80 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  ),void*,sqlite3_
34d90 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a  int64);.#endif..
34da0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
34db0 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75  Obtaining SQL Fu
34dc0 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72  nction Parameter
34dd0 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68   Values.**.** Th
34de0 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70  e C-language imp
34df0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53  lementation of S
34e00 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
34e10 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73   aggregates uses
34e20 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20  .** this set of 
34e30 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e  interface routin
34e40 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  es to access the
34e50 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65   parameter value
34e60 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63  s on.** the func
34e70 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74  tion or aggregat
34e80 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75  e..**.** The xFu
34e90 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66  nc (for scalar f
34ea0 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74  unctions) or xSt
34eb0 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74  ep (for aggregat
34ec0 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  es) parameters.*
34ed0 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
34ee0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
34ef0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
34f00 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
34f10 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c  )].** define cal
34f20 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c  lbacks that impl
34f30 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75  ement the SQL fu
34f40 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
34f50 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33  egates..** The 3
34f60 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
34f70 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20  these callbacks 
34f80 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
34f90 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70  ointers to.** [p
34fa0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
34fb0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
34fc0 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b    There is one [
34fd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
34fe0 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63  bject for.** eac
34ff0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
35000 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e  he SQL function.
35010 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73    These routines
35020 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20   are used to.** 
35030 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66  extract values f
35040 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
35050 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
35060 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
35070 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20  tines work only 
35080 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20  with [protected 
35090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
350a0 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61  bjects..** Any a
350b0 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
350c0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20  ese routines on 
350d0 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  an [unprotected 
350e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
350f0 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73  * object results
35100 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65   in undefined be
35110 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  havior..**.** ^T
35120 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
35130 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65  rk just like the
35140 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b   corresponding [
35150 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
35160 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65  nctions].** exce
35170 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72  pt that  these r
35180 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73  outines take a s
35190 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64  ingle [protected
351a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
351b0 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65  object.** pointe
351c0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b  r instead of a [
351d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70  sqlite3_stmt*] p
351e0 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e  ointer and an in
351f0 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d  teger column num
35200 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ber..**.** ^The 
35210 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
35220 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65  xt16() interface
35230 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d   extracts a UTF-
35240 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20  16 string.** in 
35250 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d  the native byte-
35260 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73  order of the hos
35270 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65  t machine.  ^The
35280 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
35290 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64  e_text16be() and
352a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
352b0 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66  ext16le() interf
352c0 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20  aces.** extract 
352d0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61  UTF-16 strings a
352e0 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64  s big-endian and
352f0 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72   little-endian r
35300 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a  espectively..**.
35310 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
35320 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74  _value_numeric_t
35330 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ype() interface 
35340 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c  attempts to appl
35350 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66  y.** numeric aff
35360 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c  inity to the val
35370 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20  ue.  This means 
35380 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20  that an attempt 
35390 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f  is.** made to co
353a0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
353b0 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72  to an integer or
353c0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e   floating point.
353d0 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63    If.** such a c
353e0 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73  onversion is pos
353f0 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f  sible without lo
35400 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f  ss of informatio
35410 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77  n (in other.** w
35420 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c  ords, if the val
35430 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74  ue is a string t
35440 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61  hat looks like a
35450 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e   number).** then
35460 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20   the conversion 
35470 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f  is performed.  O
35480 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76  therwise no conv
35490 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a  ersion occurs..*
354a0 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e  * The [SQLITE_IN
354b0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
354c0 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69  ] after conversi
354d0 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  on is returned.)
354e0 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70  ^.**.** Please p
354f0 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74  ay particular at
35500 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66  tention to the f
35510 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69  act that the poi
35520 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  nter returned.**
35530 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76   from [sqlite3_v
35540 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73  alue_blob()], [s
35550 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
35560 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  t()], or.** [sql
35570 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
35580 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61  6()] can be inva
35590 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62  lidated by a sub
355a0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a  sequent call to.
355b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ** [sqlite3_valu
355c0 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c  e_bytes()], [sql
355d0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
355e0 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  16()], [sqlite3_
355f0 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
35600 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
35610 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a  lue_text16()]..*
35620 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
35630 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  nes must be call
35640 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
35650 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68   thread as.** th
35660 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
35670 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65  hat supplied the
35680 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a   [sqlite3_value*
35690 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f  ] parameters..*/
356a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
356b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
356c0 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74  value_blob(sqlit
356d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
356e0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
356f0 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 73  e3_value_bytes(s
35700 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
35710 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
35720 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
35730 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  es16(sqlite3_val
35740 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
35750 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f   double sqlite3_
35760 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
35770 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
35780 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
35790 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73  ite3_value_int(s
357a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
357b0 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74  SQLITE_API sqlit
357c0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
357d0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
357e0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
357f0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 75  LITE_API const u
35800 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
35810 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
35820 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
35830 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
35840 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
35850 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
35860 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
35870 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
35880 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
35890 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c  lue_text16le(sql
358a0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
358b0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
358c0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
358d0 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69  ue_text16be(sqli
358e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
358f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
35900 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
35910 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
35920 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
35930 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
35940 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65  eric_type(sqlite
35950 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a  3_value*);../*.*
35960 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
35970 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75 6e  in Aggregate Fun
35980 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a  ction Context.**
35990 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  .** Implementati
359a0 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74 65  ons of aggregate
359b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75   SQL functions u
359c0 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69  se this.** routi
359d0 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  ne to allocate m
359e0 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e  emory for storin
359f0 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a  g their state..*
35a00 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
35a10 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33  time the sqlite3
35a20 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
35a30 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
35a40 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f  is called .** fo
35a50 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 61  r a particular a
35a60 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
35a70 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c  n, SQLite.** all
35a80 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f  ocates N of memo
35a90 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74  ry, zeroes out t
35aa0 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20  hat memory, and 
35ab0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
35ac0 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20  r.** to the new 
35ad0 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f  memory. ^On seco
35ae0 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  nd and subsequen
35af0 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  t calls to.** sq
35b00 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
35b10 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68  context() for th
35b20 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
35b30 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
35b40 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  ce,.** the same 
35b50 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72 6e  buffer is return
35b60 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67  ed.  Sqlite3_agg
35b70 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
35b80 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20   is normally.** 
35b90 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20  called once for 
35ba0 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20  each invocation 
35bb0 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61 6c  of the xStep cal
35bc0 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f  lback and then o
35bd0 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20  ne.** last time 
35be0 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  when the xFinal 
35bf0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
35c00 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20  ked.  ^(When no 
35c10 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e  rows match.** an
35c20 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
35c30 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63 61  , the xStep() ca
35c40 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67  llback of the ag
35c50 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
35c60 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
35c70 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c  on is never call
35c80 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20  ed and xFinal() 
35c90 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c  is called exactl
35ca0 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68  y once..** In th
35cb0 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74  ose cases, sqlit
35cc0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
35cd0 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65 20  text() might be 
35ce0 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a  called for the.*
35cf0 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f  * first time fro
35d00 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28  m within xFinal(
35d10 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ).)^.**.** ^The 
35d20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
35d30 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72  e_context(C,N) r
35d40 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61  outine returns a
35d50 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66   NULL pointer if
35d60 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68   N is.** less th
35d70 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
35d80 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f  ero or if a memo
35d90 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f  ry allocate erro
35da0 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20  r occurs..**.** 
35db0 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20  ^(The amount of 
35dc0 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20  space allocated 
35dd0 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  by sqlite3_aggre
35de0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e  gate_context(C,N
35df0 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e  ) is.** determin
35e00 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61  ed by the N para
35e10 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73  meter on first s
35e20 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20  uccessful call. 
35e30 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a   Changing the.**
35e40 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73   value of N in s
35e50 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
35e60 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  o sqlite3_aggreg
35e70 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69  ate_context() wi
35e80 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65  thin.** the same
35e90 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74   aggregate funct
35ea0 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c  ion instance wil
35eb0 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65  l not resize the
35ec0 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
35ed0 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ation.)^.**.** ^
35ee0 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63  SQLite automatic
35ef0 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20 6d  ally frees the m
35f00 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64 20  emory allocated 
35f10 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61  by .** sqlite3_a
35f20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
35f30 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67 72  () when the aggr
35f40 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e 63  egate query conc
35f50 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ludes..**.** The
35f60 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
35f70 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79 20   must be a copy 
35f80 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
35f90 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c  e3_context | SQL
35fa0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78   function contex
35fb0 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20 66  t] that is the f
35fc0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a 2a  irst parameter.*
35fd0 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20 6f  * to the xStep o
35fe0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
35ff0 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20 69  k routine that i
36000 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61 67  mplements the ag
36010 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74  gregate.** funct
36020 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
36030 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
36040 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
36050 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
36060 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67 72  hich.** the aggr
36070 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
36080 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
36090 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
360a0 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65  d *sqlite3_aggre
360b0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c  gate_context(sql
360c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
360d0 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a  nt nBytes);../*.
360e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65  ** CAPI3REF: Use
360f0 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74  r Data For Funct
36100 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
36110 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
36120 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
36130 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a  turns a copy of.
36140 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74  ** the pointer t
36150 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65  hat was the pUse
36160 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20  rData parameter 
36170 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74  (the 5th paramet
36180 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
36190 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
361a0 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
361b0 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
361c0 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
361d0 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
361e0 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
361f0 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
36200 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
36210 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  nction..**.** Th
36220 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20  is routine must 
36230 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
36240 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
36250 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61  n which.** the a
36260 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36270 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ed function is r
36280 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
36290 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
362a0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71  te3_user_data(sq
362b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
362c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
362d0 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
362e0 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69  ction For Functi
362f0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
36300 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
36310 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72  b_handle() inter
36320 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63  face returns a c
36330 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f  opy of.** the po
36340 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61  inter to the [da
36350 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36360 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61  n] (the 1st para
36370 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65  meter).** of the
36380 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
36390 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20  _function()].** 
363a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
363b0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
363c0 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  ] routines that 
363d0 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65  originally.** re
363e0 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70  gistered the app
363f0 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64  lication defined
36400 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51   function..*/.SQ
36410 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
36420 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   *sqlite3_contex
36430 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  t_db_handle(sqli
36440 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
36450 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36460 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69 61  Function Auxilia
36470 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68  ry Data.**.** Th
36480 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20  e following two 
36490 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
364a0 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72 20   used by scalar 
364b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  SQL functions to
364c0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d 65  .** associate me
364d0 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67 75  tadata with argu
364e0 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66 20  ment values. If 
364f0 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20 69  the same value i
36500 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d  s passed to.** m
36510 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74 69  ultiple invocati
36520 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
36530 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75 72  SQL function dur
36540 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75 74  ing query execut
36550 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f  ion, under.** so
36560 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73  me circumstances
36570 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64 20   the associated 
36580 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65 20  metadata may be 
36590 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73 20  preserved. This 
365a0 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20  may.** be used, 
365b0 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  for example, to 
365c0 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65 78  add a regular-ex
365d0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
365e0 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63  g scalar.** func
365f0 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c  tion. The compil
36600 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
36610 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  e regular expres
36620 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20 61  sion is stored a
36630 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
36640 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
36650 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73 73  e SQL value pass
36660 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c 61  ed as the regula
36670 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20  r expression.** 
36680 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63 6f  pattern.  The co
36690 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
366a0 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
366b0 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
366c0 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
366d0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
366e0 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74 20  unction so that 
366f0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61 74  the original pat
36700 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64  tern string.** d
36710 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
36720 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e  be recompiled on
36730 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
36740 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36750 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
36760 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
36770 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
36780 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  o the metadata.*
36790 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79 20  * associated by 
367a0 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
367b0 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74 69  auxdata() functi
367c0 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68 20  on with the Nth 
367d0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75  argument.** valu
367e0 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  e to the applica
367f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36800 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65  ction. ^If no me
36810 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20  tadata has been 
36820 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74  ever.** been set
36830 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72 67   for the Nth arg
36840 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75 6e  ument of the fun
36850 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65  ction, or if the
36860 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
36870 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  * function param
36880 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65 64  eter has changed
36890 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61 2d   since the meta-
368a0 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a  data was set,.**
368b0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67 65   then sqlite3_ge
368c0 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74 75  t_auxdata() retu
368d0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
368e0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
368f0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
36900 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ta() interface s
36910 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61 74  aves the metadat
36920 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20  a.** pointed to 
36930 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  by its 3rd param
36940 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74 61  eter as the meta
36950 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d 74  data for the N-t
36960 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66  h.** argument of
36970 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36980 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36990 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a 2a  n.  Subsequent.*
369a0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
369b0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
369c0 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74 68   might return th
369d0 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20 68  is data, if it h
369e0 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64  as.** not been d
369f0 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66  estroyed..** ^If
36a00 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c   it is not NULL,
36a10 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76   SQLite will inv
36a20 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63 74  oke the destruct
36a30 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67  or.** function g
36a40 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68 20  iven by the 4th 
36a50 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
36a60 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
36a70 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74  () on.** the met
36a80 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20 63  adata when the c
36a90 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e  orresponding fun
36aa0 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
36ab0 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68  changes.** or wh
36ac0 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
36ad0 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20  ment completes, 
36ae0 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
36af0 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  first..**.** SQL
36b00 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20 63  ite is free to c
36b10 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63 74  all the destruct
36b20 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74 61  or and drop meta
36b30 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70  data on any.** p
36b40 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79 20  arameter of any 
36b50 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79 20  function at any 
36b60 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79  time.  ^The only
36b70 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74 68   guarantee is th
36b80 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72 75  at.** the destru
36b90 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61 6c  ctor will be cal
36ba0 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20 6d  led before the m
36bb0 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70 70  etadata is dropp
36bc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70  ed..**.** ^(In p
36bd0 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74  ractice, metadat
36be0 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62  a is preserved b
36bf0 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20  etween function 
36c00 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70  calls for.** exp
36c10 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61 72  ressions that ar
36c20 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f  e constant at co
36c30 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69 73  mpile time. This
36c40 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72 61   includes litera
36c50 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20  l.** values and 
36c60 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a  [parameters].)^.
36c70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
36c80 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
36c90 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
36ca0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
36cb0 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e  h.** the SQL fun
36cc0 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
36cd0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
36ce0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67 65  void *sqlite3_ge
36cf0 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
36d00 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
36d10 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  N);.SQLITE_API v
36d20 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  oid sqlite3_set_
36d30 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f  auxdata(sqlite3_
36d40 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c  context*, int N,
36d50 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29   void*, void (*)
36d60 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a  (void*));.../*.*
36d70 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73  * CAPI3REF: Cons
36d80 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53  tants Defining S
36d90 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f  pecial Destructo
36da0 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a  r Behavior.**.**
36db0 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69   These are speci
36dc0 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68  al values for th
36dd0 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61  e destructor tha
36de0 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61  t is passed in a
36df0 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61  s the.** final a
36e00 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69  rgument to routi
36e10 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
36e20 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d  3_result_blob()]
36e30 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72  .  ^If the destr
36e40 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e  uctor.** argumen
36e50 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54  t is SQLITE_STAT
36e60 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  IC, it means tha
36e70 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f  t the content po
36e80 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e  inter is constan
36e90 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65  t.** and will ne
36ea0 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20  ver change.  It 
36eb0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
36ec0 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20   be destroyed.  
36ed0 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54  ^The.** SQLITE_T
36ee0 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d  RANSIENT value m
36ef0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f  eans that the co
36f00 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c  ntent will likel
36f10 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74  y change in.** t
36f20 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61  he near future a
36f30 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73  nd that SQLite s
36f40 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f  hould make its o
36f50 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
36f60 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  of.** the conten
36f70 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69  t before returni
36f80 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79  ng..**.** The ty
36f90 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61  pedef is necessa
36fa0 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e  ry to work aroun
36fb0 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65  d problems in ce
36fc0 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d  rtain.** C++ com
36fd0 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63  pilers.  See tic
36fe0 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79  ket #2191..*/.ty
36ff0 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
37000 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
37010 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64  type)(void*);.#d
37020 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41  efine SQLITE_STA
37030 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74  TIC      ((sqlit
37040 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
37050 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51  pe)0).#define SQ
37060 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20  LITE_TRANSIENT  
37070 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72   ((sqlite3_destr
37080 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a  uctor_type)-1)..
37090 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
370a0 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75  Setting The Resu
370b0 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e  lt Of An SQL Fun
370c0 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ction.**.** Thes
370d0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75  e routines are u
370e0 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63  sed by the xFunc
370f0 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62   or xFinal callb
37100 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70  acks that.** imp
37110 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74  lement SQL funct
37120 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
37130 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71  tes.  See.** [sq
37140 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
37150 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
37160 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
37170 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f  ction16()].** fo
37180 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
37190 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
371a0 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
371b0 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c  work very much l
371c0 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74  ike the [paramet
371d0 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69  er binding] fami
371e0 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f  ly of.** functio
371f0 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20  ns used to bind 
37200 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70  values to host p
37210 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65  arameters in pre
37220 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
37230 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68  ..** Refer to th
37240 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  e [SQL parameter
37250 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  ] documentation 
37260 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  for additional i
37270 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
37280 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
37290 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74  esult_blob() int
372a0 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
372b0 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61  result from.** a
372c0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
372d0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
372e0 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68  o be the BLOB wh
372f0 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70  ose content is p
37300 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20  ointed.** to by 
37310 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
37320 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69  eter and which i
37330 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77  s N bytes long w
37340 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
37350 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
37360 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37370 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
37380 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
37390 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74  s set the result
373a0 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69   of.** the appli
373b0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
373c0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
373d0 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20  BLOB containing 
373e0 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65  all zero.** byte
373f0 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e  s and N bytes in
37400 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69   size, where N i
37410 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
37420 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
37430 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
37440 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62  ite3_result_doub
37450 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  le() interface s
37460 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66  ets the result f
37470 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63  rom.** an applic
37480 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
37490 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66  nction to be a f
374a0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61  loating point va
374b0 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  lue specified.**
374c0 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75   by its 2nd argu
374d0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
374e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
374f0 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
37500 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37510 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  16() functions.*
37520 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c  * cause the impl
37530 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63  emented SQL func
37540 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e  tion to throw an
37550 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e   exception..** ^
37560 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20  SQLite uses the 
37570 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74  string pointed t
37580 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20  o by the.** 2nd 
37590 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
375a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
375b0 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  r() or sqlite3_r
375c0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
375d0 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f  ** as the text o
375e0 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  f an error messa
375f0 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74  ge.  ^SQLite int
37600 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f  erprets the erro
37610 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72  r.** message str
37620 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ing from sqlite3
37630 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
37640 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74  as UTF-8. ^SQLit
37650 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20  e.** interprets 
37660 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  the string from 
37670 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37680 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d  rror16() as UTF-
37690 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20  16 in native.** 
376a0 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66  byte order.  ^If
376b0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
376c0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
376d0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a  result_error().*
376e0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  * or sqlite3_res
376f0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73  ult_error16() is
37700 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53   negative then S
37710 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74  QLite takes as t
37720 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73  he error.** mess
37730 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20  age all text up 
37740 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
37750 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
37760 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69  ..** ^If the thi
37770 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  rd parameter to 
37780 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37790 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  rror() or.** sql
377a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
377b0 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67  r16() is non-neg
377c0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
377d0 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e  e takes that man
377e0 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20  y.** bytes (not 
377f0 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d  characters) from
37800 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
37810 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20  er as the error 
37820 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65  message..** ^The
37830 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37840 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69  error() and sqli
37850 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37860 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  16().** routines
37870 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20   make a private 
37880 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f  copy of the erro
37890 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62  r message text b
378a0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65  efore.** they re
378b0 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68  turn.  Hence, th
378c0 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
378d0 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74  on can deallocat
378e0 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74  e or.** modify t
378f0 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68  he text after th
37900 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75  ey return withou
37910 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20  t harm..** ^The 
37920 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
37930 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63  rror_code() func
37940 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65  tion changes the
37950 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72   error code.** r
37960 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74  eturned by SQLit
37970 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66  e as a result of
37980 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66   an error in a f
37990 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65  unction.  ^By de
379a0 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72  fault,.** the er
379b0 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49  ror code is SQLI
379c0 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75  TE_ERROR.  ^A su
379d0 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
379e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
379f0 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71  error().** or sq
37a00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37a10 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68  or16() resets th
37a20 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20  e error code to 
37a30 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a  SQLITE_ERROR..**
37a40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37a50 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f  _result_error_to
37a60 6f 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  obig() interface
37a70 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
37a80 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72  o throw an.** er
37a90 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
37aa0 68 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20  hat a string or 
37ab0 42 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67  BLOB is too long
37ac0 20 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a   to represent..*
37ad0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37ae0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
37af0 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65  omem() interface
37b00 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74   causes SQLite t
37b10 6f 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72  o throw an.** er
37b20 72 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74  ror indicating t
37b30 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  hat a memory all
37b40 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a  ocation failed..
37b50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37b60 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20  e3_result_int() 
37b70 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
37b80 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
37b90 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
37ba0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
37bb0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
37bc0 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69   32-bit signed i
37bd0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
37be0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
37bf0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54   argument..** ^T
37c00 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37c10 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66  t_int64() interf
37c20 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
37c30 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
37c40 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
37c50 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
37c60 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69   to be the 64-bi
37c70 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
37c80 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
37c90 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
37ca0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
37cb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
37cc0 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20  ull() interface 
37cd0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
37ce0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
37cf0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37d00 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
37d10 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  be NULL..**.** ^
37d20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37d30 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74  lt_text(), sqlit
37d40 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37d50 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72  (),.** sqlite3_r
37d60 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29  esult_text16le()
37d70 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  , and sqlite3_re
37d80 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20  sult_text16be() 
37d90 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65  interfaces.** se
37da0 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  t the return val
37db0 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ue of the applic
37dc0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
37dd0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20  nction to be.** 
37de0 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68  a text string wh
37df0 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74  ich is represent
37e00 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46  ed as UTF-8, UTF
37e10 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20  -16 native byte 
37e20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36  order,.** UTF-16
37e30 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20   little endian, 
37e40 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e  or UTF-16 big en
37e50 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65  dian, respective
37e60 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74  ly..** ^SQLite t
37e70 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65  akes the text re
37e80 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70  sult from the ap
37e90 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a  plication from.*
37ea0 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  * the 2nd parame
37eb0 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ter of the sqlit
37ec0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
37ed0 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e  interfaces..** ^
37ee0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
37ef0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
37f00 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
37f10 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
37f20 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
37f30 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65   SQLite takes re
37f40 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74  sult text from t
37f50 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
37f60 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20  .** through the 
37f70 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61  first zero chara
37f80 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  cter..** ^If the
37f90 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
37fa0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
37fb0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
37fc0 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d  faces.** is non-
37fd0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61  negative, then a
37fe0 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f  s many bytes (no
37ff0 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66  t characters) of
38000 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69   the text.** poi
38010 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32  nted to by the 2
38020 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65  nd parameter are
38030 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70   taken as the ap
38040 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
38050 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65  d.** function re
38060 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72  sult.  If the 3r
38070 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e  d parameter is n
38080 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
38090 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20  n it.** must be 
380a0 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20  the byte offset 
380b0 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20  into the string 
380c0 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65  where the NUL te
380d0 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a  rminator would.*
380e0 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20  * appear if the 
380f0 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c  string where NUL
38100 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66   terminated.  If
38110 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74   any NUL charact
38120 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20  ers occur.** in 
38130 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20  the string at a 
38140 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74  byte offset that
38150 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68   is less than th
38160 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33  e value of the 3
38170 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  rd.** parameter,
38180 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74   then the result
38190 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  ing string will 
381a0 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
381b0 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a   NULs and the.**
381c0 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
381d0 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67  ssions operating
381e0 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68   on strings with
381f0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
38200 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
38210 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
38220 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
38230 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
38240 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
38250 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
38260 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d  t_blob is a non-
38270 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
38280 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20  en SQLite calls 
38290 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  that.** function
382a0 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74   as the destruct
382b0 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f  or on the text o
382c0 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68  r BLOB result wh
382d0 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e  en it has.** fin
382e0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
382f0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
38300 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
38310 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
38320 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
38330 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a  terfaces or to.*
38340 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
38350 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65  _blob is the spe
38360 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51  cial constant SQ
38370 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65  LITE_STATIC, the
38380 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75  n SQLite.** assu
38390 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78  mes that the tex
383a0 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74  t or BLOB result
383b0 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20   is in constant 
383c0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
383d0 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63  ot.** copy the c
383e0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61  ontent of the pa
383f0 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c  rameter nor call
38400 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e   a destructor on
38410 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   the content.** 
38420 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69  when it has fini
38430 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
38440 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
38450 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
38460 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
38470 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
38480 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
38490 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
384a0 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
384b0 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
384c0 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68  _TRANSIENT.** th
384d0 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20  en SQLite makes 
384e0 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65  a copy of the re
384f0 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20  sult into space 
38500 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a  obtained from.**
38510 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
38520 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20  alloc()] before 
38530 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a  it returns..**.*
38540 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
38550 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e  esult_value() in
38560 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
38570 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68   result of.** th
38580 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
38590 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
385a0 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a  o be a copy the.
385b0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
385c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
385d0 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20  bject specified 
385e0 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  by the 2nd param
385f0 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  eter.  ^The.** s
38600 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
38610 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  lue() interface 
38620 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
38630 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
38640 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74  ue].** so that t
38650 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
38660 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20  e] specified in 
38670 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61  the parameter ma
38680 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62  y change or.** b
38690 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66  e deallocated af
386a0 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75  ter sqlite3_resu
386b0 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72  lt_value() retur
386c0 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e  ns without harm.
386d0 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65  .** ^A [protecte
386e0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
386f0 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61   object may alwa
38700 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65  ys be used where
38710 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
38720 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
38730 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71  e] object is req
38740 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72  uired, so either
38750 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c  .** kind of [sql
38760 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
38770 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77  ct can be used w
38780 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61  ith this interfa
38790 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ce..**.** If the
387a0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
387b0 63