System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 01516ac9abfd658ae08ec0f8725d72325755d83e:


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 34 2e 20 20  ersion 3.7.14.  
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 34 22 0a         "3.7.14".
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 34 0a 23 64 65 66 69 6e 65 20 53 51  07014.#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 32 2d 30 39 2d 30 33 20      "2012-09-03 
5db0: 31 31 3a 33 39 3a 35 39 20 61 31 35 61 37 30 38  11:39:59 a15a708
5dc0: 34 30 65 31 61 66 35 35 66 66 65 34 30 33 35 66  40e1af55ffe4035f
5dd0: 35 33 65 38 39 34 61 32 64 35 38 32 64 38 66 37  53e894a2d582d8f7
5de0: 34 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  4"../*.** 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 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
a2f0: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
a300: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
a310: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
a320: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
a330: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
a340: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
a350: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
a360: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
a370: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
a380: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
a390: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
a3a0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
a3b0: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
a3c0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
a3d0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
a3e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
a3f0: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
a400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
a410: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
a420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
a430: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
a440: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
a450: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
a460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a470: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
a480: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
a490: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
a4a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a4b0: 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b  E_ABORT_ROLLBACK
a4c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
a4d0: 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29  E_ABORT | (2<<8)
a4e0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
a4f0: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
a500: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
a510: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
a520: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
a530: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
a540: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
a550: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
a560: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
a570: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
a580: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
a590: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
a5a0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
a5b0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
a5c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a5d0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
a5e0: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
a5f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a600: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a620: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
a630: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
a640: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a650: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a670: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
a680: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
a690: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a6a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a6b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a6c0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
a6d0: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
a6e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a6f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a700: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
a710: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
a720: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a740: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
a750: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
a760: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a780: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
a790: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
a7a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a7b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a7c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a7d0: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
a7e0: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
a7f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a800: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a820: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
a830: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
a840: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a860: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
a870: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
a880: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a8a0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
a8b0: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
a8c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a8d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a8e0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
a8f0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
a900: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a910: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a920: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
a930: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
a940: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a960: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
a970: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
a980: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a990: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a9a0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
a9b0: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
a9c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a9d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a9e0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
a9f0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
aa00: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
aa10: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
aa20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
aa30: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
aa40: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
aa50: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
aa60: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
aa70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
aa80: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
aa90: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
aaa0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
aab0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
aac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
aad0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
aae0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
aaf0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
ab00: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
ab10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
ab20: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
ab30: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
ab40: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
ab50: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
ab60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
ab70: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
ab80: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ab90: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
aba0: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
abb0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
abc0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
abd0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
abe0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
abf0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
ac00: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
ac10: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
ac20: 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75  hese.** bit valu
ac30: 65 73 20 65 78 70 72 65 73 73 69 6e 67 20 49 2f  es expressing I/
ac40: 4f 20 63 68 61 72 61 63 74 65 72 69 73 74 69 63  O characteristic
ac50: 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20 73 74  s of the mass st
ac60: 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63 65 20  orage.** device 
ac70: 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65 20 66  that holds the f
ac80: 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b 73 71  ile that the [sq
ac90: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
aca0: 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a  ].** refers to..
acb0: 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  **.** The SQLITE
acc0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72  _IOCAP_ATOMIC pr
acd0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
ace0: 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a  t all writes of.
acf0: 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20  ** any size are 
ad00: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
ad10: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
ad20: 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65  nnn values.** me
ad30: 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f  an that writes o
ad40: 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72  f blocks that ar
ad50: 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73  e nnn bytes in s
ad60: 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61  ize and.** are a
ad70: 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64  ligned to an add
ad80: 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e  ress which is an
ad90: 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c   integer multipl
ada0: 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20  e of.** nnn are 
adb0: 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c  atomic.  The SQL
adc0: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
add0: 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e  PPEND value mean
ade0: 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64  s.** that when d
adf0: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20  ata is appended 
ae00: 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64  to a file, the d
ae10: 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a  ata is appended.
ae20: 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68  ** first then th
ae30: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69  e size of the fi
ae40: 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20  le is extended, 
ae50: 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a  never the other.
ae60: 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20  ** way around.  
ae70: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
ae80: 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70  _SEQUENTIAL prop
ae90: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
aea0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  ** information i
aeb0: 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  s written to dis
aec0: 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72  k in the same or
aed0: 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20  der as calls.** 
aee0: 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20 54 68  to xWrite().  Th
aef0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
af00: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
af10: 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  TE property mean
af20: 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65 72 20  s that.** after 
af30: 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67  reboot following
af40: 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f 77 65   a crash or powe
af50: 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79  r loss, the only
af60: 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66   bytes in a.** f
af70: 69 6c 65 20 74 68 61 74 20 77 65 72 65 20 77 72  ile that were wr
af80: 69 74 74 65 6e 20 61 74 20 74 68 65 20 61 70 70  itten at the app
af90: 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d  lication level m
afa0: 69 67 68 74 20 68 61 76 65 20 63 68 61 6e 67 65  ight have change
afb0: 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 61 64  d.** and that ad
afc0: 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20 65 76  jacent bytes, ev
afd0: 65 6e 20 62 79 74 65 73 20 77 69 74 68 69 6e 20  en bytes within 
afe0: 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f 72 20  the same sector 
aff0: 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  are.** guarantee
b000: 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e 67 65  d to be unchange
b010: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
b020: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
b030: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
b040: 20 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65    0x00000001.#de
b050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
b060: 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20  P_ATOMIC512     
b070: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
b080: 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  002.#define SQLI
b090: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
b0a0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
b0b0: 30 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69  0x00000004.#defi
b0c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
b0d0: 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20  ATOMIC2K        
b0e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
b0f0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
b100: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20  _IOCAP_ATOMIC4K 
b110: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
b120: 30 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65  00000010.#define
b130: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
b140: 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20  OMIC8K          
b150: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a       0x00000020.
b160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
b170: 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20  OCAP_ATOMIC16K  
b180: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
b190: 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53  000040.#define S
b1a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
b1b0: 49 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20  IC32K           
b1c0: 20 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64     0x00000080.#d
b1d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
b1e0: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20  AP_ATOMIC64K    
b1f0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
b200: 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0100.#define SQL
b210: 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41  ITE_IOCAP_SAFE_A
b220: 50 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20  PPEND           
b230: 20 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66   0x00000200.#def
b240: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
b250: 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20  _SEQUENTIAL     
b260: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34          0x000004
b270: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
b280: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
b290: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30  BLE_WHEN_OPEN  0
b2a0: 78 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e  x00000800.#defin
b2b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50  e SQLITE_IOCAP_P
b2c0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
b2d0: 54 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30  TE    0x00001000
b2e0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b2f0: 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c  : File Locking L
b300: 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  evels.**.** SQLi
b310: 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66 20 74  te uses one of t
b320: 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c  hese integer val
b330: 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ues as the secon
b340: 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f  d.** argument to
b350: 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20   calls it makes 
b360: 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61  to the xLock() a
b370: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74  nd xUnlock() met
b380: 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73  hods.** of an [s
b390: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
b3a0: 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64  s] object..*/.#d
b3b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
b3c0: 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20 20 20  K_NONE          
b3d0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b3e0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20 20 20  _LOCK_SHARED    
b3f0: 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
b400: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
b410: 45 44 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e  ED      2.#defin
b420: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45  e SQLITE_LOCK_PE
b430: 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a 23 64  NDING       3.#d
b440: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
b450: 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20  K_EXCLUSIVE     
b460: 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  4../*.** CAPI3RE
b470: 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69  F: Synchronizati
b480: 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a  on Type Flags.**
b490: 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74 65 20  .** When SQLite 
b4a0: 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53 79 6e  invokes the xSyn
b4b0: 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  c() method of an
b4c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  .** [sqlite3_io_
b4d0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
b4e0: 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62 69 6e  it uses a combin
b4f0: 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73  ation of.** thes
b500: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
b510: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
b520: 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57  rgument..**.** W
b530: 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45 5f 53  hen the SQLITE_S
b540: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61  YNC_DATAONLY fla
b550: 67 20 69 73 20 75 73 65 64 2c 20 69 74 20 6d 65  g is used, it me
b560: 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ans that the.** 
b570: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f  sync operation o
b580: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66 6c 75  nly needs to flu
b590: 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73 73 20  sh data to mass 
b5a0: 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a  storage.  Inode.
b5b0: 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e  ** information n
b5c0: 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75 73 68  eed not be flush
b5d0: 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77 65 72  ed. If the lower
b5e0: 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20 74 68   four bits of th
b5f0: 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20  e flag.** equal 
b600: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
b610: 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  AL, that means t
b620: 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79  o use normal fsy
b630: 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a  nc() semantics..
b640: 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20  ** If the lower 
b650: 66 6f 75 72 20 62 69 74 73 20 65 71 75 61 6c 20  four bits equal 
b660: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
b670: 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20  , that means.** 
b680: 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20 58 20  to use Mac OS X 
b690: 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69  style fullsync i
b6a0: 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e 63 28  nstead of fsync(
b6b0: 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20  )..**.** Do not 
b6c0: 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51 4c 49  confuse the SQLI
b6d0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
b6e0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
b6f0: 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74  ULL flags.** wit
b700: 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20 73 79  h the [PRAGMA sy
b710: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41  nchronous]=NORMA
b720: 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20 73 79  L and [PRAGMA sy
b730: 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a  nchronous]=FULL.
b740: 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20 54 68  ** settings.  Th
b750: 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70  e [synchronous p
b760: 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65  ragma] determine
b770: 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  s when calls to 
b780: 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53  the.** xSync VFS
b790: 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20 61 6e   method occur an
b7a0: 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66 6f 72  d applies unifor
b7b0: 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c 20 70  mly across all p
b7c0: 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65  latforms..** The
b7d0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
b7e0: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
b7f0: 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64  YNC_FULL flags d
b800: 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20  etermine how.** 
b810: 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72 69 67  energetic or rig
b820: 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65 66 75  orous or forcefu
b830: 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65 72 61  l the sync opera
b840: 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a  tions are and.**
b850: 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64 69 66   only make a dif
b860: 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f  ference on Mac O
b870: 53 58 20 66 6f 72 20 74 68 65 20 64 65 66 61 75  SX for the defau
b880: 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a  lt SQLite code..
b890: 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74 79 20  ** (Third-party 
b8a0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
b8b0: 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d  ons might also m
b8c0: 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74  ake the distinct
b8d0: 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53  ion.** between S
b8e0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
b8f0: 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e  L and SQLITE_SYN
b900: 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e  C_FULL, but amon
b910: 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69  g the.** operati
b920: 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74 69 76  ng systems nativ
b930: 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20 62 79  ely supported by
b940: 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61   SQLite, only Ma
b950: 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73 20 61  c OSX.** cares a
b960: 62 6f 75 74 20 74 68 65 20 64 69 66 66 65 72 65  bout the differe
b970: 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65  nce.).*/.#define
b980: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
b990: 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30 30 30  MAL        0x000
b9a0: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
b9b0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20  E_SYNC_FULL     
b9c0: 20 20 20 20 20 30 78 30 30 30 30 33 0a 23 64 65       0x00003.#de
b9d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
b9e0: 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20 20 30  _DATAONLY      0
b9f0: 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  x00010../*.** CA
ba00: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
ba10: 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65 20 48  face Open File H
ba20: 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b  andle.**.** An [
ba30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
ba40: 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20  ject represents 
ba50: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20  an open file in 
ba60: 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
ba70: 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65 72 66  _vfs | OS interf
ba80: 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64  ace layer].  Ind
ba90: 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74 65 72  ividual OS inter
baa0: 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  face.** implemen
bab0: 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20  tations will.** 
bac0: 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61 73 73  want to subclass
bad0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62 79 20   this object by 
bae0: 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69 74 69  appending additi
baf0: 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66  onal fields.** f
bb00: 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75 73 65  or their own use
bb10: 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64 73 20  .  The pMethods 
bb20: 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69 6e 74  entry is a point
bb30: 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c  er to an.** [sql
bb40: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
bb50: 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65 66   object that def
bb60: 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66 6f 72  ines methods for
bb70: 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49   performing.** I
bb80: 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e  /O operations on
bb90: 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a   the open file..
bba0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
bbb0: 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 73  t sqlite3_file s
bbc0: 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72  qlite3_file;.str
bbd0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
bbe0: 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72 75 63   {.  const struc
bbf0: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
bc00: 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20  hods *pMethods; 
bc10: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f 72 20   /* Methods for 
bc20: 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a  an open file */.
bc30: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
bc40: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
bc50: 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20 4d 65   File Virtual Me
bc60: 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a  thods Object.**.
bc70: 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20 6f 70  ** Every file op
bc80: 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ened by the [sql
bc90: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
bca0: 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74 65 73  method populates
bcb0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
bcc0: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72  file] object (or
bcd0: 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c  , more commonly,
bce0: 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66 20 74   a subclass of t
bcf0: 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  he.** [sqlite3_f
bd00: 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77 69 74  ile] object) wit
bd10: 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  h a pointer to a
bd20: 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
bd30: 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68  is object..** Th
bd40: 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
bd50: 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20 75 73  s the methods us
bd60: 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ed to perform va
bd70: 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f 6e 73  rious operations
bd80: 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68 65 20  .** against the 
bd90: 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72 65 73  open file repres
bda0: 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b 73 71  ented by the [sq
bdb0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
bdc0: 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65  ct..**.** If the
bdd0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
bde0: 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65 74 73  pen] method sets
bdf0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
be00: 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65  e.pMethods eleme
be10: 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d  nt .** to a non-
be20: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
be30: 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  en the sqlite3_i
be40: 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65  o_methods.xClose
be50: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62   method.** may b
be60: 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69  e invoked even i
be70: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  f the [sqlite3_v
be80: 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74  fs.xOpen] report
be90: 65 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65  ed that it faile
bea0: 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20  d.  The.** only 
beb0: 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61  way to prevent a
bec0: 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20   call to xClose 
bed0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c  following a fail
bee0: 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  ed [sqlite3_vfs.
bef0: 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72  xOpen].** is for
bf00: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
bf10: 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20  s.xOpen] to set 
bf20: 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
bf30: 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e  .pMethods elemen
bf40: 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  t.** to NULL..**
bf50: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
bf60: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
bf70: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
bf80: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
bf90: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
bfa0: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
bfb0: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
bfc0: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
bfd0: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
bfe0: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
bff0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
c000: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
c010: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
c020: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
c030: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
c040: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
c050: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
c060: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
c070: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
c080: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
c090: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
c0a0: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
c0b0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
c0c0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
c0d0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
c0e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
c0f0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c100: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
c110: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
c120: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
c130: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
c140: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
c150: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c160: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
c170: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
c180: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
c190: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
c1a0: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
c1b0: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
c1c0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
c1d0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
c1e0: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
c1f0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
c200: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
c210: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
c220: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
c230: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
c240: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
c250: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
c260: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
c270: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
c280: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
c290: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
c2a0: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
c2b0: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
c2c0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
c2d0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
c2e0: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
c2f0: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
c300: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
c310: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
c320: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
c330: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
c340: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
c350: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
c360: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
c370: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
c380: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
c390: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
c3a0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
c3b0: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
c3c0: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
c3d0: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
c3e0: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
c3f0: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
c400: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
c410: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
c420: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
c430: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
c440: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
c450: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
c460: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
c470: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
c480: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
c490: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
c4a0: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
c4b0: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
c4c0: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
c4d0: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
c4e0: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
c4f0: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
c500: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
c510: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
c520: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
c530: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
c540: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
c550: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
c560: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49   use..** A [SQLI
c570: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
c580: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  TE | list of opc
c590: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
c5a0: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
c5b0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
c5c0: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
c5d0: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
c5e0: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
c5f0: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a  d use opcodes.**
c600: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30   greater than 10
c610: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c  0 to avoid confl
c620: 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65  icts.  VFS imple
c630: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
c640: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
c650: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f  ITE_NOTFOUND] fo
c660: 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  r file control o
c670: 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79  pcodes that they
c680: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67   do not.** recog
c690: 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nize..**.** The 
c6a0: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65  xSectorSize() me
c6b0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65  thod returns the
c6c0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20   sector size of 
c6d0: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  the.** device th
c6e0: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65  at underlies the
c6f0: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74   file.  The sect
c700: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a  or size is the.*
c710: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20  * minimum write 
c720: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66  that can be perf
c730: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69  ormed without di
c740: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65  sturbing.** othe
c750: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  r bytes in the f
c760: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63  ile.  The xDevic
c770: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
c780: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
c790: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f  urns a bit vecto
c7a0: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68  r describing beh
c7b0: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a  aviors of the.**
c7c0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69   underlying devi
c7d0: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce:.**.** <ul>.*
c7e0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
c7f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20  OCAP_ATOMIC].** 
c800: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
c810: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a  AP_ATOMIC512].**
c820: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
c830: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a  CAP_ATOMIC1K].**
c840: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
c850: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a  CAP_ATOMIC2K].**
c860: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
c870: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a  CAP_ATOMIC4K].**
c880: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
c890: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a  CAP_ATOMIC8K].**
c8a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
c8b0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a  CAP_ATOMIC16K].*
c8c0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
c8d0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a  OCAP_ATOMIC32K].
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 36 34 4b 5d  IOCAP_ATOMIC64K]
c900: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c910: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
c920: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ND].** <li> [SQL
c930: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
c940: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  TIAL].** </ul>.*
c950: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
c960: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
c970: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
c980: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
c990: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
c9a0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
c9b0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
c9c0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
c9d0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
c9e0: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
c9f0: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
ca00: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
ca10: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
ca20: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
ca30: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
ca40: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
ca50: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
ca60: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
ca70: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
ca80: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
ca90: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
caa0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
cab0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
cac0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
cad0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
cae0: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
caf0: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
cb00: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
cb10: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
cb20: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
cb30: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
cb40: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
cb50: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
cb60: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
cb70: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
cb80: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
cb90: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
cba0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
cbb0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
cbc0: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
cbd0: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
cbe0: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
cbf0: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
cc00: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
cc10: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
cc20: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
cc30: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
cc40: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
cc50: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
cc60: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
cc70: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
cc80: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
cc90: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
cca0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
ccb0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
ccc0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
ccd0: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
cce0: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
ccf0: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
cd00: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
cd10: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
cd20: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
cd30: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
cd40: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
cd50: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
cd60: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
cd70: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
cd80: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
cd90: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
cda0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
cdb0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
cdc0: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
cdd0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
cde0: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
cdf0: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
ce00: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
ce10: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
ce20: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
ce30: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
ce40: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
ce50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
ce60: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
ce70: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
ce80: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
ce90: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
cea0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
ceb0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
cec0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
ced0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
cee0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
cef0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
cf00: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
cf10: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
cf20: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
cf30: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
cf40: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
cf50: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
cf60: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
cf70: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
cf80: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
cf90: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
cfa0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
cfb0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
cfc0: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
cfd0: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
cfe0: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
cff0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
d000: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
d010: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
d020: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
d030: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
d040: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
d050: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
d060: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
d070: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
d080: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
d090: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
d0a0: 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  2 */.  /* Additi
d0b0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
d0c0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
d0d0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
d0e0: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
d0f0: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
d100: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
d110: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  s.**.** These in
d120: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
d130: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
d140: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
d150: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
d160: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
d170: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
d180: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
d190: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
d1a0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
d1b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
d1c0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
d1d0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
d1e0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
d1f0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
d200: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
d210: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
d220: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
d230: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
d240: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
d250: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
d260: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
d270: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
d280: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
d290: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
d2a0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
d2b0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
d2c0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
d2d0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
d2e0: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
d2f0: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
d300: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
d310: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
d320: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
d330: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
d340: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
d350: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
d360: 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e  defined..** <ul>
d370: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
d380: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
d390: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
d3a0: 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e  E_FCNTL_SIZE_HIN
d3b0: 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  T] opcode is use
d3c0: 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67  d by SQLite to g
d3d0: 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c  ive the VFS.** l
d3e0: 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68  ayer a hint of h
d3f0: 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64 61 74  ow large the dat
d400: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
d410: 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e  grow to be durin
d420: 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  g the.** current
d430: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54   transaction.  T
d440: 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20  his hint is not 
d450: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
d460: 20 61 63 63 75 72 61 74 65 20 62 75 74 20 69 74   accurate but it
d470: 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f  .** is often clo
d480: 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79  se.  The underly
d490: 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20 63 68  ing VFS might ch
d4a0: 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63  oose to prealloc
d4b0: 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ate database.** 
d4c0: 66 69 6c 65 20 73 70 61 63 65 20 62 61 73 65 64  file space based
d4d0: 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e   on this hint in
d4e0: 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77   order to help w
d4f0: 72 69 74 65 73 20 74 6f 20 74 68 65 20 64 61 74  rites to the dat
d500: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75  abase.** file ru
d510: 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  n faster..**.** 
d520: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
d530: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a  TL_CHUNK_SIZE]].
d540: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
d550: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
d560: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
d570: 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74 20  to request that 
d580: 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e  the VFS.** exten
d590: 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73  ds and truncates
d5a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
d5b0: 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20  le in chunks of 
d5c0: 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65 64  a size specified
d5d0: 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e  .** by the user.
d5e0: 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   The fourth argu
d5f0: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
d600: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
d610: 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e   should .** poin
d620: 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  t to an integer 
d630: 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61  (type int) conta
d640: 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68  ining the new ch
d650: 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a  unk-size to use.
d660: 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e  ** for the nomin
d670: 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 41  ated database. A
d680: 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61  llocating databa
d690: 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e  se file space in
d6a0: 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73   large.** chunks
d6b0: 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20 74   (say 1MB at a t
d6c0: 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65  ime), may reduce
d6d0: 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61   file-system fra
d6e0: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a  gmentation and.*
d6f0: 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  * improve perfor
d700: 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79  mance on some sy
d710: 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  stems..**.** <li
d720: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
d730: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a  FILE_POINTER]].*
d740: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
d750: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
d760: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
d770: 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69   to obtain a poi
d780: 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  nter.** to the [
d790: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
d7a0: 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64 20  ject associated 
d7b0: 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
d7c0: 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  r database.** co
d7d0: 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74  nnection.  See t
d7e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
d7f0: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75  _control()] docu
d800: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
d810: 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
d820: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c  rmation..**.** <
d830: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
d840: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d  L_SYNC_OMITTED]]
d850: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
d860: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
d870: 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69 73 20  TTED] opcode is 
d880: 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e  generated intern
d890: 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74  ally by.** SQLit
d8a0: 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c  e and sent to al
d8b0: 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61 63 65  l VFSes in place
d8c0: 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20 74 68   of a call to th
d8d0: 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a  e xSync method.*
d8e0: 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  * when the datab
d8f0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68  ase connection h
d900: 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  as [PRAGMA synch
d910: 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f  ronous] set to O
d920: 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70  FF.)^.** Some sp
d930: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 20  ecialized VFSes 
d940: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
d950: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 70 65   in order to ope
d960: 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a  rate correctly.*
d970: 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41 20 73  * when [PRAGMA s
d980: 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41  ynchronous | PRA
d990: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d  GMA synchronous=
d9a0: 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62 75 74  OFF] is set, but
d9b0: 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65 73 20   most .** VFSes 
d9c0: 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73  do not need this
d9d0: 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75   signal and shou
d9e0: 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f  ld silently igno
d9f0: 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a  re this opcode..
da00: 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
da10: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
da20: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
da30: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
da40: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20  is.** opcode as 
da50: 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69 73  doing so may dis
da60: 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74 69  rupt the operati
da70: 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61  on of the specia
da80: 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a 20 74  lized VFSes.** t
da90: 68 61 74 20 64 6f 20 72 65 71 75 69 72 65 20 69  hat do require i
daa0: 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  t.  .**.** <li>[
dab0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
dac0: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a  N32_AV_RETRY]].*
dad0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
dae0: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
daf0: 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TRY] opcode is u
db00: 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75 72 65  sed to configure
db10: 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65   automatic.** re
db20: 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64 20 69  try counts and i
db30: 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63 65 72  ntervals for cer
db40: 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70  tain disk I/O op
db50: 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74 68 65  erations for the
db60: 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56 46 53  .** windows [VFS
db70: 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  ] in order to pr
db80: 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65 73 73  ovide robustness
db90: 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e 63 65   in the presence
dba0: 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75   of.** anti-viru
dbb0: 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42 79 20  s programs.  By 
dbc0: 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77 69 6e  default, the win
dbd0: 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20 72 65  dows VFS will re
dbe0: 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a  try file read,.*
dbf0: 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20 61 6e  * file write, an
dc00: 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20 6f 70  d file delete op
dc10: 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f 20 31  erations up to 1
dc20: 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20 61 20  0 times, with a 
dc30: 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d  delay.** of 25 m
dc40: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65 66 6f  illiseconds befo
dc50: 72 65 20 74 68 65 20 66 69 72 73 74 20 72 65 74  re the first ret
dc60: 72 79 20 61 6e 64 20 77 69 74 68 20 74 68 65 20  ry and with the 
dc70: 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69 6e 67  delay increasing
dc80: 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69 74 69  .** by an additi
dc90: 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63  onal 25 millisec
dca0: 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68 20 73  onds with each s
dcb0: 75 62 73 65 71 75 65 6e 74 20 72 65 74 72 79 2e  ubsequent retry.
dcc0: 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65    This.** opcode
dcd0: 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20 74 77   allows these tw
dce0: 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72 65 74  o values (10 ret
dcf0: 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c  ries and 25 mill
dd00: 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61  iseconds of dela
dd10: 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75  y).** to be adju
dd20: 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c 75 65  sted.  The value
dd30: 73 20 61 72 65 20 63 68 61 6e 67 65 64 20 66 6f  s are changed fo
dd40: 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65 20 63  r all database c
dd50: 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69  onnections.** wi
dd60: 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 70 72  thin the same pr
dd70: 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72 67 75  ocess.  The argu
dd80: 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
dd90: 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20 6f 66  r to an array of
dda0: 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73   two.** integers
ddb0: 20 77 68 65 72 65 20 74 68 65 20 66 69 72 73 74   where the first
ddc0: 20 69 6e 74 65 67 65 72 20 69 20 74 68 65 20 6e   integer i the n
ddd0: 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74 20 61  ew retry count a
dde0: 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  nd the second.**
ddf0: 20 69 6e 74 65 67 65 72 20 69 73 20 74 68 65 20   integer is the 
de00: 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74 68 65  delay.  If eithe
de10: 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e 65 67  r integer is neg
de20: 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20  ative, then the 
de30: 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f  setting.** is no
de40: 74 20 63 68 61 6e 67 65 64 20 62 75 74 20 69 6e  t changed but in
de50: 73 74 65 61 64 20 74 68 65 20 70 72 69 6f 72 20  stead the prior 
de60: 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 73 65  value of that se
de70: 74 74 69 6e 67 20 69 73 20 77 72 69 74 74 65 6e  tting is written
de80: 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61 72 72  .** into the arr
de90: 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69  ay entry, allowi
dea0: 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74 20 72  ng the current r
deb0: 65 74 72 79 20 73 65 74 74 69 6e 67 73 20 74 6f  etry settings to
dec0: 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61   be.** interroga
ded0: 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d  ted.  The zDbNam
dee0: 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  e parameter is i
def0: 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  gnored..**.** <l
df00: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
df10: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a  _PERSIST_WAL]].*
df20: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
df30: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
df40: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
df50: 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79   to set or query
df60: 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65   the.** persiste
df70: 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74 65 20  nt [WAL | Write 
df80: 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74 74 69  Ahead Log] setti
df90: 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c  ng.  By default,
dfa0: 20 74 68 65 20 61 75 78 69 6c 69 61 72 79 0a 2a   the auxiliary.*
dfb0: 2a 20 77 72 69 74 65 20 61 68 65 61 64 20 6c 6f  * write ahead lo
dfc0: 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  g and shared mem
dfd0: 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64 20 66  ory files used f
dfe0: 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 63  or transaction c
dff0: 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75  ontrol.** are au
e000: 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c 65  tomatically dele
e010: 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c 61 74  ted when the lat
e020: 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  est connection t
e030: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
e040: 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74 74 69  * closes.  Setti
e050: 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  ng persistent WA
e060: 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20 74 68  L mode causes th
e070: 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70 65 72  ose files to per
e080: 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c  sist after.** cl
e090: 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69 6e 67  ose.  Persisting
e0a0: 20 74 68 65 20 66 69 6c 65 73 20 69 73 20 75 73   the files is us
e0b0: 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65 72 20  eful when other 
e0c0: 70 72 6f 63 65 73 73 65 73 20 74 68 61 74 20 64  processes that d
e0d0: 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72  o not.** have wr
e0e0: 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f  ite permission o
e0f0: 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72 79 20  n the directory 
e100: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 64  containing the d
e110: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 6e  atabase file wan
e120: 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74 68 65  t.** to read the
e130: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
e140: 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64 20 73  as the WAL and s
e150: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
e160: 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a  es must exist.**
e170: 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20 74 68   in order for th
e180: 65 20 64 61 74 61 62 61 73 65 20 74 6f 20 62 65  e database to be
e190: 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20   readable.  The 
e1a0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
e1b0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
e1c0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
e1d0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
e1e0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
e1f0: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
e200: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
e210: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
e220: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20 57 41  le persistent WA
e230: 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  L mode or 1 to e
e240: 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74  nable persistent
e250: 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49  .** WAL mode.  I
e260: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
e270: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
e280: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
e290: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
e2a0: 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63 65 20  WAL persistence 
e2b0: 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c  setting..**.** <
e2c0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
e2d0: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
e2e0: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
e2f0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
e300: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
e310: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
e320: 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65 72  d to set or quer
e330: 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73 74  y the.** persist
e340: 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65 2d 6f  ent "powersafe-o
e350: 76 65 72 77 72 69 74 65 22 20 6f 72 20 22 50 53  verwrite" or "PS
e360: 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20 54 68  OW" setting.  Th
e370: 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a  e PSOW setting.*
e380: 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  * determines the
e390: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50   [SQLITE_IOCAP_P
e3a0: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
e3b0: 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65 0a 2a  TE] bit of the.*
e3c0: 2a 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74  * xDeviceCharact
e3d0: 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64 73  eristics methods
e3e0: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70 61 72  . The fourth par
e3f0: 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
e400: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
e410: 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f  ol()] for this o
e420: 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20  pcode should be 
e430: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
e440: 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74  integer..** That
e450: 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f   integer is 0 to
e460: 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61   disable zero-da
e470: 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31 20 74  mage mode or 1 t
e480: 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61  o enable zero-da
e490: 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49  mage.** mode.  I
e4a0: 66 20 74 68 65 20 69 6e 74 65 67 65 72 20 69 73  f the integer is
e4b0: 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69 73 20   -1, then it is 
e4c0: 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69 74 68  overwritten with
e4d0: 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
e4e0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
e4f0: 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20   setting..**.** 
e500: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
e510: 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  TL_OVERWRITE]].*
e520: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
e530: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20  CNTL_OVERWRITE] 
e540: 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65  opcode is invoke
e550: 64 20 62 79 20 53 51 4c 69 74 65 20 61 66 74 65  d by SQLite afte
e560: 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77  r opening.** a w
e570: 72 69 74 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  rite transaction
e580: 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61   to indicate tha
e590: 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69 73 20  t, unless it is 
e5a0: 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f 72 20  rolled back for 
e5b0: 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20  some.** reason, 
e5c0: 74 68 65 20 65 6e 74 69 72 65 20 64 61 74 61 62  the entire datab
e5d0: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  ase file will be
e5e0: 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62 79 20   overwritten by 
e5f0: 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20  the current .** 
e600: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69  transaction. Thi
e610: 73 20 69 73 20 75 73 65 64 20 62 79 20 56 41 43  s is used by VAC
e620: 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  UUM operations..
e630: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
e640: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
e650: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
e660: 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45  TE_FCNTL_VFSNAME
e670: 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62 65 20  ] opcode can be 
e680: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74  used to obtain t
e690: 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61  he names of.** a
e6a0: 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20 74 68  ll [VFSes] in th
e6b0: 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20 54 68  e VFS stack.  Th
e6c0: 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66 20 61  e names are of a
e6d0: 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61 6e 64  ll VFS shims and
e6e0: 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f   the.** final bo
e6f0: 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61  ttom-level VFS a
e700: 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  re written into 
e710: 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
e720: 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  from .** [sqlite
e730: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
e740: 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 73 74  the result is st
e750: 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68 61 72  ored in the char
e760: 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68  * variable.** th
e770: 61 74 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  at the fourth pa
e780: 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71 6c 69  rameter of [sqli
e790: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
e7a0: 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a  ()] points to..*
e7b0: 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69 73 20  * The caller is 
e7c0: 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
e7d0: 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f  freeing the memo
e7e0: 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41  ry when done.  A
e7f0: 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69  s with.** all fi
e800: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f  le-control actio
e810: 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ns, there is no 
e820: 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20 74  guarantee that t
e830: 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c  his will actuall
e840: 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67  y.** do anything
e850: 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c  .  Callers shoul
e860: 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  d initialize the
e870: 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 20   char* variable 
e880: 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  to a NULL.** poi
e890: 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74 68 69  nter in case thi
e8a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69  s file-control i
e8b0: 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65  s not implemente
e8c0: 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d 63 6f  d.  This file-co
e8d0: 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65  ntrol.** is inte
e8e0: 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e 6f 73  nded for diagnos
e8f0: 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a  tic use only..**
e900: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
e910: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a  _FCNTL_PRAGMA]].
e920: 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61 20 5b  ** ^Whenever a [
e930: 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e  PRAGMA] statemen
e940: 74 20 69 73 20 70 61 72 73 65 64 2c 20 61 6e 20  t is parsed, an 
e950: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
e960: 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63  AGMA] .** file c
e970: 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74 20 74  ontrol is sent t
e980: 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69  o the open [sqli
e990: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
e9a0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a   corresponding.*
e9b0: 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  * to the databas
e9c0: 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63 68 20  e file to which 
e9d0: 74 68 65 20 70 72 61 67 6d 61 20 73 74 61 74 65  the pragma state
e9e0: 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e 54 68  ment refers. ^Th
e9f0: 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f  e argument.** to
ea00: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   the [SQLITE_FCN
ea10: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
ea20: 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20 61 72  control is an ar
ea30: 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65  ray of.** pointe
ea40: 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 28 63  rs to strings (c
ea50: 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63 68 20  har**) in which 
ea60: 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65  the second eleme
ea70: 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61 79 0a  nt of the array.
ea80: 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
ea90: 66 20 74 68 65 20 70 72 61 67 6d 61 20 61 6e 64  f the pragma and
eaa0: 20 74 68 65 20 74 68 69 72 64 20 65 6c 65 6d 65   the third eleme
eab0: 6e 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  nt is the argume
eac0: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61  nt to the.** pra
ead0: 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  gma or NULL if t
eae0: 68 65 20 70 72 61 67 6d 61 20 68 61 73 20 6e 6f  he pragma has no
eaf0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65   argument.  ^The
eb00: 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a   handler for an.
eb10: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
eb20: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
eb30: 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e  ntrol can option
eb40: 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20 66 69  ally make the fi
eb50: 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f  rst element.** o
eb60: 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61 72 67  f the char** arg
eb70: 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61  ument point to a
eb80: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
eb90: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
eba0: 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20  printf()].** or 
ebb0: 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74 20 61  the equivalent a
ebc0: 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67 20 77  nd that string w
ebd0: 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65 20 72  ill become the r
ebe0: 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70 72 61  esult of the pra
ebf0: 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72  gma or.** the er
ec00: 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66 20 74  ror message if t
ec10: 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c 73 2e  he pragma fails.
ec20: 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
ec30: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
ec40: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  ] file control r
ec50: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e  eturns [SQLITE_N
ec60: 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e  OTFOUND], then n
ec70: 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d  ormal .** [PRAGM
ec80: 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20 63 6f  A] processing co
ec90: 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20 74 68  ntinues.  ^If th
eca0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ecb0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
ecc0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
ecd0: 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65  [SQLITE_OK], the
ece0: 6e 20 74 68 65 20 70 61 72 73 65 72 20 61 73 73  n the parser ass
ecf0: 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
ed00: 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c 65 64   VFS has handled
ed10: 20 74 68 65 20 50 52 41 47 4d 41 20 69 74 73 65   the PRAGMA itse
ed20: 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72 73 65  lf and the parse
ed30: 72 20 67 65 6e 65 72 61 74 65 73 20 61 20 6e 6f  r generates a no
ed40: 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65 64 20  -op.** prepared 
ed50: 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20  statement.  ^If 
ed60: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
ed70: 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63  L_PRAGMA] file c
ed80: 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a  ontrol returns.*
ed90: 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63 6f 64  * any result cod
eda0: 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51  e other than [SQ
edb0: 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c  LITE_OK] or [SQL
edc0: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74  ITE_NOTFOUND], t
edd0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  hat means.** tha
ede0: 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f 75 6e  t the VFS encoun
edf0: 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72 20 77  tered an error w
ee00: 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20 74 68  hile handling th
ee10: 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64 20 74  e [PRAGMA] and t
ee20: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f  he.** compilatio
ee30: 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d 41 20  n of the PRAGMA 
ee40: 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20 65 72  fails with an er
ee50: 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49  ror.  ^The [SQLI
ee60: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
ee70: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
ee80: 20 6f 63 63 75 72 73 20 61 74 20 74 68 65 20 62   occurs at the b
ee90: 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67  eginning of prag
eea0: 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 61  ma statement ana
eeb0: 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20  lysis and so.** 
eec0: 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20 6f 76  it is able to ov
eed0: 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69 6e 20  erride built-in 
eee0: 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d 65  [PRAGMA] stateme
eef0: 6e 74 73 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f  nts..** </ul>.*/
ef00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ef10: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
ef20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
ef30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 47  #define SQLITE_G
ef40: 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45  ET_LOCKPROXYFILE
ef50: 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
ef60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
ef70: 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20  T_LOCKPROXYFILE 
ef80: 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
ef90: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53  efine SQLITE_LAS
efa0: 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20  T_ERRNO         
efb0: 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
efc0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
efd0: 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20  L_SIZE_HINT     
efe0: 20 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66            5.#def
eff0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
f000: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
f010: 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
f020: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
f030: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20  FILE_POINTER    
f040: 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
f050: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
f060: 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20  YNC_OMITTED     
f070: 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65         8.#define
f080: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49   SQLITE_FCNTL_WI
f090: 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20  N32_AV_RETRY    
f0a0: 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
f0b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
f0c0: 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20  SIST_WAL        
f0d0: 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53      10.#define S
f0e0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
f0f0: 57 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20  WRITE           
f100: 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51     11.#define SQ
f110: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
f120: 4d 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ME              
f130: 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c    12.#define SQL
f140: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
f150: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20  AFE_OVERWRITE   
f160: 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   13.#define SQLI
f170: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20  TE_FCNTL_PRAGMA 
f180: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
f190: 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  14../*.** CAPI3R
f1a0: 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64 6c 65  EF: Mutex Handle
f1b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78  .**.** The mutex
f1c0: 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e 20 53   module within S
f1d0: 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20 5b 73  QLite defines [s
f1e0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f  qlite3_mutex] to
f1f0: 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61   be an.** abstra
f200: 63 74 20 74 79 70 65 20 66 6f 72 20 61 20 6d 75  ct type for a mu
f210: 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54 68 65  tex object.  The
f220: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e 65 76   SQLite core nev
f230: 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74  er looks.** at t
f240: 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
f250: 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e  esentation of an
f260: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d   [sqlite3_mutex]
f270: 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65  .  It only.** de
f280: 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74 65 72  als with pointer
f290: 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
f2a0: 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e  3_mutex] object.
f2b0: 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61  .**.** Mutexes a
f2c0: 72 65 20 63 72 65 61 74 65 64 20 75 73 69 6e 67  re created using
f2d0: 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
f2e0: 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70  alloc()]..*/.typ
f2f0: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
f300: 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69 74 65  te3_mutex sqlite
f310: 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20  3_mutex;../*.** 
f320: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
f330: 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a  erface Object.**
f340: 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
f350: 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  of the sqlite3_v
f360: 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  fs object define
f370: 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
f380: 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53  between.** the S
f390: 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64 20 74  QLite core and t
f3a0: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70  he underlying op
f3b0: 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
f3c0: 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e   The "vfs".** in
f3d0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
f3e0: 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73 20 66   object stands f
f3f0: 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69 6c 65  or "virtual file
f400: 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a   system".  See.*
f410: 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56 46 53  * the [VFS | VFS
f420: 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
f430: 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e 66 6f  for further info
f440: 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
f450: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
f460: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 69  iVersion field i
f470: 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20 62 75  s initially 1 bu
f480: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 20  t may be larger 
f490: 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76 65 72  in.** future ver
f4a0: 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
f4b0: 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66 69 65    Additional fie
f4c0: 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
f4d0: 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f  ded to this.** o
f4e0: 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65 20 69  bject when the i
f4f0: 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20 69 73  Version value is
f500: 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e 6f 74   increased.  Not
f510: 65 20 74 68 61 74 20 74 68 65 20 73 74 72 75 63  e that the struc
f520: 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73  ture.** of the s
f530: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
f540: 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  t changes in the
f550: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 74   transaction bet
f560: 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76  ween.** SQLite v
f570: 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64  ersion 3.5.9 and
f580: 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74 20 74   3.6.0 and yet t
f590: 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c  he iVersion fiel
f5a0: 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64  d was not.** mod
f5b0: 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ified..**.** The
f5c0: 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c 64 20   szOsFile field 
f5d0: 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
f5e0: 68 65 20 73 75 62 63 6c 61 73 73 65 64 20 5b 73  he subclassed [s
f5f0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20  qlite3_file].** 
f600: 73 74 72 75 63 74 75 72 65 20 75 73 65 64 20 62  structure used b
f610: 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d 78 50  y this VFS.  mxP
f620: 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65 20 6d  athname is the m
f630: 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
f640: 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65 20 69  .** a pathname i
f650: 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a  n this VFS..**.*
f660: 2a 20 52 65 67 69 73 74 65 72 65 64 20 73 71 6c  * Registered sql
f670: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 73  ite3_vfs objects
f680: 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c   are kept on a l
f690: 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72 6d 65  inked list forme
f6a0: 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78  d by.** the pNex
f6b0: 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  t pointer.  The 
f6c0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72 65 67  [sqlite3_vfs_reg
f6d0: 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20  ister()].** and 
f6e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72  [sqlite3_vfs_unr
f6f0: 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74 65 72  egister()] inter
f700: 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74 68 69  faces manage thi
f710: 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74  s list.** in a t
f720: 68 72 65 61 64 2d 73 61 66 65 20 77 61 79 2e 20  hread-safe way. 
f730: 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   The [sqlite3_vf
f740: 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65 72 66  s_find()] interf
f750: 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65 73 20  ace.** searches 
f760: 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69 74 68  the list.  Neith
f770: 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
f780: 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68 65 20  on code nor the 
f790: 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  VFS.** implement
f7a0: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ation should use
f7b0: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
f7c0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e  er..**.** The pN
f7d0: 65 78 74 20 66 69 65 6c 64 20 69 73 20 74 68 65  ext field is the
f7e0: 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e 20 74   only field in t
f7f0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
f800: 2a 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74  * structure that
f810: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 76 65   SQLite will eve
f820: 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c 69 74  r modify.  SQLit
f830: 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65  e will only acce
f840: 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20  ss.** or modify 
f850: 74 68 69 73 20 66 69 65 6c 64 20 77 68 69 6c 65  this field while
f860: 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72 74 69   holding a parti
f870: 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d 75 74  cular static mut
f880: 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  ex..** The appli
f890: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65  cation should ne
f8a0: 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79 74 68  ver modify anyth
f8b0: 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65 20 73  ing within the s
f8c0: 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62  qlite3_vfs.** ob
f8d0: 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20 6f 62  ject once the ob
f8e0: 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20 72 65  ject has been re
f8f0: 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  gistered..**.** 
f900: 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20  The zName field 
f910: 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65 20 6f  holds the name o
f920: 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75 6c 65  f the VFS module
f930: 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75 73 74  .  The name must
f940: 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20 61 63  .** be unique ac
f950: 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64  ross all VFS mod
f960: 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71  ules..**.** [[sq
f970: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
f980: 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61  ].** ^SQLite gua
f990: 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65  rantees that the
f9a0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
f9b0: 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a  eter to xOpen.**
f9c0: 20 69 73 20 65 69 74 68 65 72 20 61 20 4e 55 4c   is either a NUL
f9d0: 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73 74 72  L pointer or str
f9e0: 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ing obtained.** 
f9f0: 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61  from xFullPathna
fa00: 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f 70 74  me() with an opt
fa10: 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61 64 64  ional suffix add
fa20: 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66  ed..** ^If a suf
fa30: 66 69 78 20 69 73 20 61 64 64 65 64 20 74 6f 20  fix is added to 
fa40: 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61  the zFilename pa
fa50: 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69 6c 6c  rameter, it will
fa60: 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66 20 61  .** consist of a
fa70: 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68 61 72   single "-" char
fa80: 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62  acter followed b
fa90: 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a  y no more than.*
faa0: 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65 72 69  * 11 alphanumeri
fab0: 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61  c and/or "-" cha
fac0: 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c  racters..** ^SQL
fad0: 69 74 65 20 66 75 72 74 68 65 72 20 67 75 61 72  ite further guar
fae0: 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a 20 74  antees that.** t
faf0: 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62  he string will b
fb00: 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e 63 68  e valid and unch
fb10: 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f  anged until xClo
fb20: 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65  se() is.** calle
fb30: 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  d. Because of th
fb40: 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
fb50: 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  nce,.** the [sql
fb60: 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73  ite3_file] can s
fb70: 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20 70 6f  afely store a po
fb80: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
fb90: 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74 20 6e  filename if it n
fba0: 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62 65 72  eeds to remember
fbb0: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f   the filename fo
fbc0: 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a  r some reason..*
fbd0: 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61  * If the zFilena
fbe0: 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  me parameter to 
fbf0: 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20  xOpen is a NULL 
fc00: 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78 4f 70  pointer then xOp
fc10: 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e  en.** must inven
fc20: 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72  t its own tempor
fc30: 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74 68 65  ary name for the
fc40: 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65   file.  ^Wheneve
fc50: 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e  r the .** xFilen
fc60: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
fc70: 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c   NULL it will al
fc80: 73 6f 20 62 65 20 74 68 65 20 63 61 73 65 20 74  so be the case t
fc90: 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73  hat the.** flags
fca0: 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c 6c 20   parameter will 
fcb0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
fcc0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
fcd0: 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  SE]..**.** The f
fce0: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
fcf0: 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75 64 65   xOpen() include
fd00: 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74 20 69  s all bits set i
fd10: 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73 20 61  n.** the flags a
fd20: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
fd30: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20  te3_open_v2()]. 
fd40: 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   Or if [sqlite3_
fd50: 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73  open()].** or [s
fd60: 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
fd70: 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e 20 66   is used, then f
fd80: 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20 61 74  lags includes at
fd90: 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54   least.** [SQLIT
fda0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
fdb0: 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  ] | [SQLITE_OPEN
fdc0: 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66  _CREATE]. .** If
fdd0: 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73 20 61   xOpen() opens a
fde0: 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20   file read-only 
fdf0: 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a 70 4f  then it sets *pO
fe00: 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e  utFlags to.** in
fe10: 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50  clude [SQLITE_OP
fe20: 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f  EN_READONLY].  O
fe30: 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a 70 4f  ther bits in *pO
fe40: 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65 20 73  utFlags may be s
fe50: 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69  et..**.** ^(SQLi
fe60: 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64  te will also add
fe70: 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
fe80: 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
fe90: 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61  he xOpen().** ca
fea0: 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ll, depending on
feb0: 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65 69 6e   the object bein
fec0: 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20  g opened:.**.** 
fed0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  <ul>.** <li>  [S
fee0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f  QLITE_OPEN_MAIN_
fef0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
ff00: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
ff10: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
ff20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45   [SQLITE_OPEN_TE
ff30: 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  MP_DB].** <li>  
ff40: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d  [SQLITE_OPEN_TEM
ff50: 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  P_JOURNAL].** <l
ff60: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ff70: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a  _TRANSIENT_DB].*
ff80: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ff90: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d  OPEN_SUBJOURNAL]
ffa0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ffb0: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
ffc0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
ffd0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c  [SQLITE_OPEN_WAL
ffe0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  ].** </ul>)^.**.
fff0: 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f 4f 20  ** The file I/O 
10000 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63  implementation c
10010 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a 65 63  an use the objec
10020 74 20 74 79 70 65 20 66 6c 61 67 73 20 74 6f 0a  t type flags to.
10030 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 77 61  ** change the wa
10040 79 20 69 74 20 64 65 61 6c 73 20 77 69 74 68 20  y it deals with 
10050 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78 61 6d  files.  For exam
10060 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74  ple, an applicat
10070 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73  ion.** that does
10080 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75 74 20   not care about 
10090 63 72 61 73 68 20 72 65 63 6f 76 65 72 79 20 6f  crash recovery o
100a0 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74  r rollback might
100b0 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65   make.** the ope
100c0 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66  n of a journal f
100d0 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72  ile a no-op.  Wr
100e0 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a 6f 75  ites to this jou
100f0 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c  rnal would.** al
10100 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e  so be no-ops, an
10110 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  d any attempt to
10120 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72 6e 61   read the journa
10130 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a  l would return.*
10140 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20  * SQLITE_IOERR. 
10150 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e   Or the implemen
10160 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 63  tation might rec
10170 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20 64 61  ognize that a da
10180 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77  tabase.** file w
10190 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70 61 67  ill be doing pag
101a0 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74 6f 72  e-aligned sector
101b0 20 72 65 61 64 73 20 61 6e 64 20 77 72 69 74 65   reads and write
101c0 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a  s in a random.**
101d0 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74 20 75   order and set u
101e0 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73 79 73  p its I/O subsys
101f0 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e  tem accordingly.
10200 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69  .**.** SQLite mi
10210 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65  ght also add one
10220 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
10230 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78  g flags to the x
10240 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Open method:.**.
10250 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
10260 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c  [SQLITE_OPEN_DEL
10270 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c  ETEONCLOSE].** <
10280 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
10290 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c  _EXCLUSIVE].** <
102a0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  /ul>.**.** The [
102b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
102c0 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20  TEONCLOSE] flag 
102d0 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65 20 73  means the file s
102e0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65  hould be.** dele
102f0 74 65 64 20 77 68 65 6e 20 69 74 20 69 73 20 63  ted when it is c
10300 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b 53 51  losed.  ^The [SQ
10310 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
10320 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c  ONCLOSE].** will
10330 20 62 65 20 73 65 74 20 66 6f 72 20 54 45 4d 50   be set for TEMP
10340 20 64 61 74 61 62 61 73 65 73 20 61 6e 64 20 74   databases and t
10350 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74  heir journals, t
10360 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61  ransient.** data
10370 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f  bases, and subjo
10380 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  urnals..**.** ^T
10390 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
103a0 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61 67 20  EXCLUSIVE] flag 
103b0 69 73 20 61 6c 77 61 79 73 20 75 73 65 64 20 69  is always used i
103c0 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a  n conjunction.**
103d0 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
103e0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 20 66  E_OPEN_CREATE] f
103f0 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65 20 62  lag, which are b
10400 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  oth directly.** 
10410 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65  analogous to the
10420 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52   O_EXCL and O_CR
10430 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74 68 65  EAT flags of the
10440 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a   POSIX open().**
10450 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c 49 54   API.  The SQLIT
10460 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
10470 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61 69 72   flag, when pair
10480 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  ed with the .** 
10490 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
104a0 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f 20 69  TE, is used to i
104b0 6e 64 69 63 61 74 65 20 74 68 61 74 20 66 69 6c  ndicate that fil
104c0 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a  e should always.
104d0 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c 20 61  ** be created, a
104e0 6e 64 20 74 68 61 74 20 69 74 20 69 73 20 61 6e  nd that it is an
104f0 20 65 72 72 6f 72 20 69 66 20 69 74 20 61 6c 72   error if it alr
10500 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20  eady exists..** 
10510 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e  It is <i>not</i>
10520 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
10530 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c  e the file shoul
10540 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20  d be opened .** 
10550 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20 61 63  for exclusive ac
10560 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20  cess..**.** ^At 
10570 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65 20 62  least szOsFile b
10580 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  ytes of memory a
10590 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
105a0 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c  SQLite.** to hol
105b0 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65 33 5f  d the  [sqlite3_
105c0 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72 65 20  file] structure 
105d0 70 61 73 73 65 64 20 61 73 20 74 68 65 20 74 68  passed as the th
105e0 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ird.** argument 
105f0 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65 20 78  to xOpen.  The x
10600 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73  Open method does
10610 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20   not have to.** 
10620 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73 74 72  allocate the str
10630 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f 75 6c  ucture; it shoul
10640 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74 20 69  d just fill it i
10650 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a  n.  Note that.**
10660 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
10670 64 20 6d 75 73 74 20 73 65 74 20 74 68 65 20 73  d must set the s
10680 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
10690 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72 0a 2a  hods to either.*
106a0 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c 69 74  * a valid [sqlit
106b0 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
106c0 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c  bject or to NULL
106d0 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f  .  xOpen must do
106e0 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20 69 66  .** this even if
106f0 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e   the open fails.
10700 20 20 53 51 4c 69 74 65 20 65 78 70 65 63 74 73    SQLite expects
10710 20 74 68 61 74 20 74 68 65 20 73 71 6c 69 74 65   that the sqlite
10720 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a  3_file.pMethods.
10730 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20  ** element will 
10740 62 65 20 76 61 6c 69 64 20 61 66 74 65 72 20 78  be valid after x
10750 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72 65 67  Open returns reg
10760 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65 20 73  ardless of the s
10770 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69  uccess.** or fai
10780 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f 70 65  lure of the xOpe
10790 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  n call..**.** [[
107a0 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41 63 63  sqlite3_vfs.xAcc
107b0 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c  ess]].** ^The fl
107c0 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
107d0 78 41 63 63 65 73 73 28 29 20 6d 61 79 20 62 65  xAccess() may be
107e0 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
107f0 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65  EXISTS].** to te
10800 73 74 20 66 6f 72 20 74 68 65 20 65 78 69 73 74  st for the exist
10810 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65 2c 20  ence of a file, 
10820 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  or [SQLITE_ACCES
10830 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74 6f 0a  S_READWRITE] to.
10840 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65 72 20  ** test whether 
10850 61 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  a file is readab
10860 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 2c  le and writable,
10870 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43 45   or [SQLITE_ACCE
10880 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74  SS_READ].** to t
10890 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66 69  est whether a fi
108a0 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74 20 72  le is at least r
108b0 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65 20 66  eadable.   The f
108c0 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20  ile can be a.** 
108d0 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a  directory..**.**
108e0 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c   ^SQLite will al
108f0 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20 61 74  ways allocate at
10900 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e 61 6d   least mxPathnam
10910 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20 74 68  e+1 bytes for th
10920 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75 66 66  e.** output buff
10930 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65  er xFullPathname
10940 2e 20 20 54 68 65 20 65 78 61 63 74 20 73 69 7a  .  The exact siz
10950 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75 74 20  e of the output 
10960 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73  buffer.** is als
10970 6f 20 70 61 73 73 65 64 20 61 73 20 61 20 70 61  o passed as a pa
10980 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74 68 20  rameter to both 
10990 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74 68 65   methods. If the
109a0 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a   output buffer.*
109b0 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65 20 65  * is not large e
109c0 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43  nough, [SQLITE_C
109d0 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20  ANTOPEN] should 
109e0 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53 69 6e  be returned. Sin
109f0 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20 68 61  ce this is.** ha
10a00 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74 61 6c  ndled as a fatal
10a10 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69 74 65   error by SQLite
10a20 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61  , vfs implementa
10a30 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64  tions should end
10a40 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76  eavor.** to prev
10a50 65 6e 74 20 74 68 69 73 20 62 79 20 73 65 74 74  ent this by sett
10a60 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65 20 74  ing mxPathname t
10a70 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74 6c 79  o a sufficiently
10a80 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a   large value..**
10a90 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e  .** The xRandomn
10aa0 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28 29 2c  ess(), xSleep(),
10ab0 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 2c   xCurrentTime(),
10ac0 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54 69 6d   and xCurrentTim
10ad0 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65  eInt64().** inte
10ae0 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74 20 73  rfaces are not s
10af0 74 72 69 63 74 6c 79 20 61 20 70 61 72 74 20 6f  trictly a part o
10b00 66 20 74 68 65 20 66 69 6c 65 73 79 73 74 65 6d  f the filesystem
10b10 2c 20 62 75 74 20 74 68 65 79 20 61 72 65 0a 2a  , but they are.*
10b20 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68  * included in th
10b30 65 20 56 46 53 20 73 74 72 75 63 74 75 72 65 20  e VFS structure 
10b40 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73  for completeness
10b50 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d  ..** The xRandom
10b60 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  ness() function 
10b70 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 74 75  attempts to retu
10b80 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65 73 0a  rn nBytes bytes.
10b90 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69  ** of good-quali
10ba0 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e  ty randomness in
10bb0 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20 72 65  to zOut.  The re
10bc0 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a  turn value is.**
10bd0 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75 6d 62   the actual numb
10be0 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 72  er of bytes of r
10bf0 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
10c00 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65  ed..** The xSlee
10c10 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75 73 65  p() method cause
10c20 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 74 68  s the calling th
10c30 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20 66 6f  read to sleep fo
10c40 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68  r at.** least th
10c50 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 63 72  e number of micr
10c60 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20  oseconds given. 
10c70 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
10c80 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  me().** method r
10c90 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20  eturns a Julian 
10ca0 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72 20 74  Day Number for t
10cb0 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 65 20  he current date 
10cc0 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61  and time as.** a
10cd0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
10ce0 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78  value..** ^The x
10cf0 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
10d00 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  () method return
10d10 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67 65 72  s, as an integer
10d20 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20  , the Julian.** 
10d30 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69  Day Number multi
10d40 70 6c 69 65 64 20 62 79 20 38 36 34 30 30 30 30  plied by 8640000
10d50 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  0 (the number of
10d60 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e   milliseconds in
10d70 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72 20 64   .** a 24-hour d
10d80 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74  ay).  .** ^SQLit
10d90 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20 78  e will use the x
10da0 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
10db0 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67 65 74  () method to get
10dc0 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
10dd0 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 69 66  date and time if
10de0 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69 73 20   that method is 
10df0 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20 69 56  available (if iV
10e00 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a  ersion is 2 or .
10e10 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64 20 74  ** greater and t
10e20 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
10e30 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29  ter is not NULL)
10e40 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62   and will fall b
10e50 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65  ack.** to xCurre
10e60 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43 75 72  ntTime() if xCur
10e70 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
10e80 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
10e90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65 74 53  **.** ^The xSetS
10ea0 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65  ystemCall(), xGe
10eb0 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61  tSystemCall(), a
10ec0 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d 43 61  nd xNestSystemCa
10ed0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  ll() interfaces.
10ee0 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65 64 20  ** are not used 
10ef0 62 79 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f  by the SQLite co
10f00 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74 69 6f  re.  These optio
10f10 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61  nal interfaces a
10f20 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62  re provided.** b
10f30 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74 6f 20  y some VFSes to 
10f40 66 61 63 69 6c 69 74 61 74 65 20 74 65 73 74 69  facilitate testi
10f50 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20 63 6f  ng of the VFS co
10f60 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64 69 6e  de. By overridin
10f70 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c  g .** system cal
10f80 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69 6f 6e  ls with function
10f90 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f 6e 74  s under its cont
10fa0 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72 6f 67  rol, a test prog
10fb0 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c  ram can.** simul
10fc0 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64 20 65  ate faults and e
10fd0 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20  rror conditions 
10fe0 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68 65 72  that would other
10ff0 77 69 73 65 20 62 65 20 64 69 66 66 69 63 75 6c  wise be difficul
11000 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62  t.** or impossib
11010 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20 20 54  le to induce.  T
11020 68 65 20 73 65 74 20 6f 66 20 73 79 73 74 65 6d  he set of system
11030 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61 6e 20   calls that can 
11040 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a  be overridden.**
11050 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65   varies from one
11060 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c   VFS to another,
11070 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65   and from one ve
11080 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d  rsion of the sam
11090 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20  e VFS to the.** 
110a0 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69  next.  Applicati
110b0 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74 68 65  ons that use the
110c0 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 6d 75  se interfaces mu
110d0 73 74 20 62 65 20 70 72 65 70 61 72 65 64 20 66  st be prepared f
110e0 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c  or any.** or all
110f0 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 72 66   of these interf
11100 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20  aces to be NULL 
11110 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62 65 68  or for their beh
11120 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a  avior to change.
11130 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65  ** from one rele
11140 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e  ase to the next.
11150 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d    Applications m
11160 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70 74 20  ust not attempt 
11170 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79  to access.** any
11180 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68 6f 64   of these method
11190 73 20 69 66 20 74 68 65 20 69 56 65 72 73 69 6f  s if the iVersio
111a0 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69 73 20  n of the VFS is 
111b0 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a  less than 3..*/.
111c0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
111d0 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c 69 74  qlite3_vfs sqlit
111e0 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65 66 20  e3_vfs;.typedef 
111f0 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 73  void (*sqlite3_s
11200 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64  yscall_ptr)(void
11210 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  );.struct sqlite
11220 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20 69 56  3_vfs {.  int iV
11230 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20 20 20  ersion;         
11240 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72 65 20     /* Structure 
11250 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
11260 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a  currently 3) */.
11270 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20    int szOsFile; 
11280 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 69             /* Si
11290 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73 65 64  ze of subclassed
112a0 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f   sqlite3_file */
112b0 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d  .  int mxPathnam
112c0 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  e;          /* M
112d0 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61 74 68  aximum file path
112e0 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20  name length */. 
112f0 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e   sqlite3_vfs *pN
11300 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78  ext;      /* Nex
11310 74 20 72 65 67 69 73 74 65 72 65 64 20 56 46 53  t registered VFS
11320 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
11330 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f   *zName;       /
11340 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73 20 76  * Name of this v
11350 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74  irtual file syst
11360 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  em */.  void *pA
11370 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
11380 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f 20 61   /* Pointer to a
11390 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65 63 69  pplication-speci
113a0 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e  fic data */.  in
113b0 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74  t (*xOpen)(sqlit
113c0 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
113d0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69  har *zName, sqli
113e0 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20  te3_file*,.     
113f0 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 66 6c            int fl
11400 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c  ags, int *pOutFl
11410 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  ags);.  int (*xD
11420 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33 5f 76  elete)(sqlite3_v
11430 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
11440 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63  *zName, int sync
11450 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41  Dir);.  int (*xA
11460 63 63 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76  ccess)(sqlite3_v
11470 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
11480 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67  *zName, int flag
11490 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  s, int *pResOut)
114a0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50  ;.  int (*xFullP
114b0 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74 65 33  athname)(sqlite3
114c0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
114d0 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f  r *zName, int nO
114e0 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b  ut, char *zOut);
114f0 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70  .  void *(*xDlOp
11500 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
11510 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  , const char *zF
11520 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64  ilename);.  void
11530 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73 71 6c   (*xDlError)(sql
11540 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e  ite3_vfs*, int n
11550 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45 72 72  Byte, char *zErr
11560 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28  Msg);.  void (*(
11570 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74 65 33  *xDlSym)(sqlite3
11580 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e  _vfs*,void*, con
11590 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c  st char *zSymbol
115a0 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64  ))(void);.  void
115b0 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c   (*xDlClose)(sql
115c0 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a  ite3_vfs*, void*
115d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61 6e 64  );.  int (*xRand
115e0 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65 33 5f  omness)(sqlite3_
115f0 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  vfs*, int nByte,
11600 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
11610 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28 73 71  int (*xSleep)(sq
11620 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
11630 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20  microseconds);. 
11640 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
11650 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ime)(sqlite3_vfs
11660 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69  *, double*);.  i
11670 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45 72 72  nt (*xGetLastErr
11680 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  or)(sqlite3_vfs*
11690 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a  , int, char *);.
116a0 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65    /*.  ** The me
116b0 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
116c0 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f 66 20  in version 1 of 
116d0 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
116e0 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e  bject.  ** defin
116f0 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68  ition.  Those th
11700 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64  at follow are ad
11710 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e 20 32  ded in version 2
11720 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20   or later.  */. 
11730 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e 74 54   int (*xCurrentT
11740 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69 74 65  imeInt64)(sqlite
11750 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f  3_vfs*, sqlite3_
11760 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20  int64*);.  /*.  
11770 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
11780 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
11790 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f 66 20  ions 1 and 2 of 
117a0 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
117b0 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73  bject..  ** Thos
117c0 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f 72 20  e below are for 
117d0 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20 67 72  version 3 and gr
117e0 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e  eater..  */.  in
117f0 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d 43 61  t (*xSetSystemCa
11800 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ll)(sqlite3_vfs*
11810 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
11820 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73 79 73  ame, sqlite3_sys
11830 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c  call_ptr);.  sql
11840 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
11850 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43 61 6c   (*xGetSystemCal
11860 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
11870 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
11880 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61  me);.  const cha
11890 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74 65 6d  r *(*xNextSystem
118a0 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
118b0 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
118c0 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a  zName);.  /*.  *
118d0 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
118e0 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
118f0 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20 33 20  ons 1 through 3 
11900 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66  of the sqlite_vf
11910 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e  s object..  ** N
11920 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  ew fields may be
11930 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66 69 67   appended in fig
11940 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20 20 54  ure versions.  T
11950 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a  he iVersion.  **
11960 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72   value will incr
11970 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72 20 74  ement whenever t
11980 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a 20 20  his happens. .  
11990 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
119a0 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72  I3REF: Flags for
119b0 20 74 68 65 20 78 41 63 63 65 73 73 20 56 46 53   the xAccess VFS
119c0 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
119d0 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
119e0 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75 73 65  tants can be use
119f0 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20 70  d as the third p
11a00 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
11a10 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
11a20 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  d of an [sqlite3
11a30 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54  _vfs] object.  T
11a40 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a  hey determine.**
11a50 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 70 65   what kind of pe
11a60 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20 78 41  rmissions the xA
11a70 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69 73 20  ccess method is 
11a80 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20  looking for..** 
11a90 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
11aa0 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65 20 78  SS_EXISTS, the x
11ab0 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
11ac0 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73 20 77   simply checks w
11ad0 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
11ae0 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20  exists..** With 
11af0 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45  SQLITE_ACCESS_RE
11b00 41 44 57 52 49 54 45 2c 20 74 68 65 20 78 41 63  ADWRITE, the xAc
11b10 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
11b20 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
11b30 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74 6f 72  e named director
11b40 79 20 69 73 20 62 6f 74 68 20 72 65 61 64 61 62  y is both readab
11b50 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c 65 0a  le and writable.
11b60 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77 6f 72  ** (in other wor
11b70 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63 61 6e  ds, if files can
11b80 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d 6f 76   be added, remov
11b90 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65 64 20  ed, and renamed 
11ba0 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69  within.** the di
11bb0 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65  rectory)..** The
11bc0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
11bd0 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74 61 6e  EADWRITE constan
11be0 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 75  t is currently u
11bf0 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a  sed only by the.
11c00 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  ** [temp_store_d
11c10 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
11c20 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20 63 6f  , though this co
11c30 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20 61 20  uld change in a 
11c40 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73  future.** releas
11c50 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  e of SQLite..** 
11c60 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45  With SQLITE_ACCE
11c70 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78 41 63  SS_READ, the xAc
11c80 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63  cess method.** c
11c90 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68  hecks whether th
11ca0 65 20 66 69 6c 65 20 69 73 20 72 65 61 64 61 62  e file is readab
11cb0 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  le.  The SQLITE_
11cc0 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f 6e 73  ACCESS_READ cons
11cd0 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72 72 65  tant is.** curre
11ce0 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74 68 6f  ntly unused, tho
11cf0 75 67 68 20 69 74 20 6d 69 67 68 74 20 62 65 20  ugh it might be 
11d00 75 73 65 64 20 69 6e 20 61 20 66 75 74 75 72 65  used in a future
11d10 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53   release of.** S
11d20 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
11d30 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
11d40 45 58 49 53 54 53 20 20 20 20 30 0a 23 64 65 66  EXISTS    0.#def
11d50 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
11d60 53 5f 52 45 41 44 57 52 49 54 45 20 31 20 20 20  S_READWRITE 1   
11d70 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41 47 4d  /* Used by PRAGM
11d80 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72  A temp_store_dir
11d90 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e  ectory */.#defin
11da0 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
11db0 52 45 41 44 20 20 20 20 20 20 32 20 20 20 2f 2a  READ      2   /*
11dc0 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a   Unused */../*.*
11dd0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
11de0 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f  s for the xShmLo
11df0 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ck VFS method.**
11e00 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
11e10 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  r constants defi
11e20 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c  ne the various l
11e30 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e  ocking operation
11e40 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20  s.** allowed by 
11e50 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  the xShmLock met
11e60 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  hod of [sqlite3_
11e70 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68  io_methods].  Th
11e80 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  e.** following a
11e90 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61  re the only lega
11ea0 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f  l combinations o
11eb0 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a  f flags to the.*
11ec0 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  * xShmLock metho
11ed0 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
11ee0 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
11ef0 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  M_LOCK | SQLITE_
11f00 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c  SHM_SHARED.** <l
11f10 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
11f20 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
11f30 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c  _EXCLUSIVE.** <l
11f40 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55  i>  SQLITE_SHM_U
11f50 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  NLOCK | SQLITE_S
11f60 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69  HM_SHARED.** <li
11f70 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e  >  SQLITE_SHM_UN
11f80 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48  LOCK | SQLITE_SH
11f90 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c  M_EXCLUSIVE.** <
11fa0 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  /ul>.**.** When 
11fb0 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73  unlocking, the s
11fc0 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20 45 58  ame SHARED or EX
11fd0 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d 75 73  CLUSIVE flag mus
11fe0 74 20 62 65 20 73 75 70 70 6c 69 65 64 20 61 73  t be supplied as
11ff0 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20 6e 6f  .** was given no
12000 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
12010 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a  ng lock.  .**.**
12020 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65   The xShmLock me
12030 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73 69 74  thod can transit
12040 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f  ion between unlo
12050 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45 44 20  cked and SHARED 
12060 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e  or.** between un
12070 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43 4c 55  locked and EXCLU
12080 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74  SIVE.  It cannot
12090 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77   transition betw
120a0 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e  een SHARED.** an
120b0 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a  d EXCLUSIVE..*/.
120c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
120d0 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  HM_UNLOCK       
120e0 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
120f0 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20  _SHM_LOCK       
12100 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
12110 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20 20 20  TE_SHM_SHARED   
12120 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
12130 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49  LITE_SHM_EXCLUSI
12140 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43  VE    8../*.** C
12150 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d  API3REF: Maximum
12160 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a   xShmLock index.
12170 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f  **.** The xShmLo
12180 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71  ck method on [sq
12190 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
121a0 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75 65 73  ] may use values
121b0 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
121c0 64 20 74 68 69 73 20 75 70 70 65 72 20 62 6f 75  d this upper bou
121d0 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66 73 65  nd as its "offse
121e0 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  t" argument..** 
121f0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
12200 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74 65 6d  will never attem
12210 70 74 20 74 6f 20 61 63 71 75 69 72 65 20 6f 72  pt to acquire or
12220 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f   release a.** lo
12230 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  ck outside of th
12240 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66  is range.*/.#def
12250 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e  ine SQLITE_SHM_N
12260 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a  LOCK        8...
12270 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
12280 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65 20 53  Initialize The S
12290 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
122a0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
122b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
122c0 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65  utine initialize
122d0 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  s the.** SQLite 
122e0 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65 20 73  library.  ^The s
122f0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
12300 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61  ) routine.** dea
12310 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72 65 73  llocates any res
12320 6f 75 72 63 65 73 20 74 68 61 74 20 77 65 72 65  ources that were
12330 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
12340 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12350 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ()..** These rou
12360 74 69 6e 65 73 20 61 72 65 20 64 65 73 69 67 6e  tines are design
12370 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70 72 6f  ed to aid in pro
12380 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
12390 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64  ion and.** shutd
123a0 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65 64 20  own on embedded 
123b0 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74  systems.  Workst
123c0 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f  ation applicatio
123d0 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69  ns using.** SQLi
123e0 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e  te normally do n
123f0 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b  ot need to invok
12400 65 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73  e either of thes
12410 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  e routines..**.*
12420 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  * A call to sqli
12430 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12440 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76   is an "effectiv
12450 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73  e" call if it is
12460 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 74 69  .** the first ti
12470 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  me sqlite3_initi
12480 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b  alize() is invok
12490 65 64 20 64 75 72 69 6e 67 20 74 68 65 20 6c 69  ed during the li
124a0 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65  fetime of.** the
124b0 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69 66 20   process, or if 
124c0 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  it is the first 
124d0 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
124e0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
124f0 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  oked.** followin
12500 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  g a call to sqli
12510 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20  te3_shutdown(). 
12520 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63   ^(Only an effec
12530 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20  tive call.** of 
12540 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12550 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20 69 6e  ze() does any in
12560 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41  itialization.  A
12570 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a  ll other calls.*
12580 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e  * are harmless n
12590 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41  o-ops.)^.**.** A
125a0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
125b0 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73 20 61  _shutdown() is a
125c0 6e 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61  n "effective" ca
125d0 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68 65 20  ll if it is the 
125e0 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f  first.** call to
125f0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
12600 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20 6c 61  n() since the la
12610 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  st sqlite3_initi
12620 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79  alize().  ^(Only
12630 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69 76 65  .** an effective
12640 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
12650 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f 65 73  _shutdown() does
12660 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c 69 7a   any deinitializ
12670 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74  ation..** All ot
12680 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c 73 20  her valid calls 
12690 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
126a0 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d 6c 65  own() are harmle
126b0 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
126c0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69  ** The sqlite3_i
126d0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e 74 65  nitialize() inte
126e0 72 66 61 63 65 20 69 73 20 74 68 72 65 61 64 73  rface is threads
126f0 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74 65 33  afe, but sqlite3
12700 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69  _shutdown().** i
12710 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71 6c 69  s not.  The sqli
12720 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69  te3_shutdown() i
12730 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20 6f 6e  nterface must on
12740 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  ly be called fro
12750 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68  m a.** single th
12760 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20  read.  All open 
12770 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
12780 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65 20 63  tions] must be c
12790 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a  losed and all.**
127a0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 72 65   other SQLite re
127b0 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62 65 20  sources must be 
127c0 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f  deallocated prio
127d0 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a  r to invoking.**
127e0 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
127f0 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67  n()..**.** Among
12800 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c 20 5e   other things, ^
12810 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12820 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  ze() will invoke
12830 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
12840 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c  nit().  Similarl
12850 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68 75 74  y, ^sqlite3_shut
12860 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69  down().** will i
12870 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73  nvoke sqlite3_os
12880 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _end()..**.** ^T
12890 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
128a0 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
128b0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
128c0 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a  OK] on success..
128d0 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20  ** ^If for some 
128e0 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  reason, sqlite3_
128f0 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
12900 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74 69 61  unable to initia
12910 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72  lize.** the libr
12920 61 72 79 20 28 70 65 72 68 61 70 73 20 69 74 20  ary (perhaps it 
12930 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
12940 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64 20 72  ocate a needed r
12950 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a 2a 20  esource such.** 
12960 61 73 20 61 20 6d 75 74 65 78 29 20 69 74 20 72  as a mutex) it r
12970 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72  eturns an [error
12980 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74 68 61   code] other tha
12990 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a  n [SQLITE_OK]..*
129a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
129b0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72  3_initialize() r
129c0 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64  outine is called
129d0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d   internally by m
129e0 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  any other.** SQL
129f0 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 73  ite interfaces s
12a00 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c 69 63  o that an applic
12a10 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f  ation usually do
12a20 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a  es not need to.*
12a30 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33  * invoke sqlite3
12a40 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
12a50 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65 78 61  rectly.  For exa
12a60 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  mple, [sqlite3_o
12a70 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20  pen()].** calls 
12a80 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12a90 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51 4c 69  ze() so the SQLi
12aa0 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20  te library will 
12ab0 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
12ac0 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  .** initialized 
12ad0 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70  when [sqlite3_op
12ae0 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20  en()] is called 
12af0 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20 62 65  if it has not be
12b00 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20   initialized.** 
12b10 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77 65 76  already.  ^Howev
12b20 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20 69 73  er, if SQLite is
12b30 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
12b40 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  he [SQLITE_OMIT_
12b50 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d  AUTOINIT].** com
12b60 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
12b70 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74 6f 6d  , then the autom
12b80 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20 73 71  atic calls to sq
12b90 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12ba0 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65  ().** are omitte
12bb0 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63  d and the applic
12bc0 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20  ation must call 
12bd0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12be0 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a  ze() directly.**
12bf0 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20   prior to using 
12c00 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  any other SQLite
12c10 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 6f 72   interface.  For
12c20 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61 62 69   maximum portabi
12c30 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72  lity,.** it is r
12c40 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
12c50 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77  applications alw
12c60 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  ays invoke sqlit
12c70 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
12c80 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72 69 6f  ** directly prio
12c90 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f  r to using any o
12ca0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
12cb0 72 66 61 63 65 2e 20 20 46 75 74 75 72 65 20 72  rface.  Future r
12cc0 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51  eleases.** of SQ
12cd0 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69 72 65  Lite may require
12ce0 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68 65 72   this.  In other
12cf0 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65 68 61   words, the beha
12d00 76 69 6f 72 20 65 78 68 69 62 69 74 65 64 0a 2a  vior exhibited.*
12d10 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  * when SQLite is
12d20 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b   compiled with [
12d30 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
12d40 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65 63 6f  INIT] might beco
12d50 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c  me the.** defaul
12d60 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20 73 6f  t behavior in so
12d70 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
12d80 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a  e of SQLite..**.
12d90 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
12da0 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69 6e 65  s_init() routine
12db0 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e 67 2d   does operating-
12dc0 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 0a  system specific.
12dd0 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f  ** initializatio
12de0 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  n of the SQLite 
12df0 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 73 71  library.  The sq
12e00 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a  lite3_os_end().*
12e10 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73  * routine undoes
12e20 20 74 68 65 20 65 66 66 65 63 74 20 6f 66 20 73   the effect of s
12e30 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
12e40 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73 6b 73  .  Typical tasks
12e50 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 62 79  .** performed by
12e60 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
12e70 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69  include allocati
12e80 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69  on or deallocati
12e90 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69 63 20  on.** of static 
12ea0 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69 74 69  resources, initi
12eb0 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f  alization of glo
12ec0 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a  bal variables,.*
12ed0 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61 20 64  * setting up a d
12ee0 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
12ef0 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20  vfs] module, or 
12f00 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20  setting up.** a 
12f10 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
12f20 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c  ation using [sql
12f30 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a  ite3_config()]..
12f40 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  **.** The applic
12f50 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76  ation should nev
12f60 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72  er invoke either
12f70 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
12f80 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
12f90 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65 63 74  _os_end() direct
12fa0 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  ly.  The applica
12fb0 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79  tion should only
12fc0 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74   invoke.** sqlit
12fd0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12fe0 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68 75 74  and sqlite3_shut
12ff0 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73 71 6c  down().  The sql
13000 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a  ite3_os_init().*
13010 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 63  * interface is c
13020 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69 63 61  alled automatica
13030 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 69  lly by sqlite3_i
13040 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a  nitialize() and.
13050 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ** sqlite3_os_en
13060 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20 62 79  d() is called by
13070 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
13080 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69 61 74  n().  Appropriat
13090 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
130a0 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74 65 33  ions for sqlite3
130b0 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73  _os_init() and s
130c0 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
130d0 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69 6e 74  ** are built int
130e0 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20 69 74  o SQLite when it
130f0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72   is compiled for
13100 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20   Unix, Windows, 
13110 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e  or OS/2..** When
13120 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64 73 20   [custom builds 
13130 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74 68 65  | built for othe
13140 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20  r platforms].** 
13150 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49  (using the [SQLI
13160 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63  TE_OS_OTHER=1] c
13170 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
13180 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70 6c 69  ption) the appli
13190 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75 70 70  cation must supp
131a0 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20 69 6d  ly a suitable im
131b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  plementation for
131c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  .** sqlite3_os_i
131d0 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  nit() and sqlite
131e0 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20  3_os_end().  An 
131f0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70  application-supp
13200 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  lied.** implemen
13210 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
13220 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72 20 73  3_os_init() or s
13230 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a  qlite3_os_end().
13240 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e 20 5b  ** must return [
13250 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
13260 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f  ccess and some o
13270 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f 64 65  ther [error code
13280 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72  ] upon.** failur
13290 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
132a0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69   int sqlite3_ini
132b0 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53  tialize(void);.S
132c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
132d0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
132e0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
132f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f   int sqlite3_os_
13300 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49  init(void);.SQLI
13310 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
13320 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b  e3_os_end(void);
13330 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13340 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54 68  : Configuring Th
13350 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79  e SQLite Library
13360 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
13370 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65  e3_config() inte
13380 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
13390 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e   make global con
133a0 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68  figuration.** ch
133b0 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65 20  anges to SQLite 
133c0 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e 65  in order to tune
133d0 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20 73   SQLite to the s
133e0 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f 66  pecific needs of
133f0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
13400 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ion.  The defaul
13410 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
13420 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
13430 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69  or most.** appli
13440 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74  cations and so t
13450 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 75  his routine is u
13460 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73  sually not neces
13470 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20  sary.  It is.** 
13480 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70 70  provided to supp
13490 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63 61  ort rare applica
134a0 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73 75  tions with unusu
134b0 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20  al needs..**.** 
134c0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  The sqlite3_conf
134d0 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
134e0 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66 65  s not threadsafe
134f0 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  .  The applicati
13500 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72  on.** must insur
13510 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72 20  e that no other 
13520 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
13530 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62 79  s are invoked by
13540 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61 64   other.** thread
13550 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f  s while sqlite3_
13560 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e 6e  config() is runn
13570 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f 72  ing.  Furthermor
13580 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e, sqlite3_confi
13590 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  g().** may only 
135a0 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72  be invoked prior
135b0 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69 74   to library init
135c0 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67  ialization using
135d0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  .** [sqlite3_ini
135e0 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  tialize()] or af
135f0 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79 20  ter shutdown by 
13600 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
13610 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c  n()]..** ^If sql
13620 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73  ite3_config() is
13630 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
13640 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
13650 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a  e()] and before.
13660 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
13670 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74 20  down()] then it 
13680 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c 49  will return SQLI
13690 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f  TE_MISUSE..** No
136a0 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68 61  te, however, tha
136b0 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t ^sqlite3_confi
136c0 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  g() can be calle
136d0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
136e0 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
136f0 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63 61  on of an applica
13700 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71  tion-defined [sq
13710 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d  lite3_os_init()]
13720 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
13730 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  t argument to sq
13740 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
13750 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20  s an integer.** 
13760 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
13770 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74 65  ption] that dete
13780 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70  rmines.** what p
13790 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69 74  roperty of SQLit
137a0 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66 69  e is to be confi
137b0 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75 65  gured.  Subseque
137c0 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  nt arguments.** 
137d0 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f  vary depending o
137e0 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72 61  n the [configura
137f0 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20  tion option].** 
13800 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
13810 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68  ument..**.** ^Wh
13820 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74 69  en a configurati
13830 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74  on option is set
13840 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  , sqlite3_config
13850 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  () returns [SQLI
13860 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74  TE_OK]..** ^If t
13870 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b  he option is unk
13880 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20 69  nown or SQLite i
13890 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74 20  s unable to set 
138a0 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68  the option.** th
138b0 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
138c0 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65  returns a non-ze
138d0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e  ro [error code].
138e0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
138f0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  nt sqlite3_confi
13900 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  g(int, ...);../*
13910 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
13920 6e 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65  nfigure database
13930 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a   connections.**.
13940 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64  ** The sqlite3_d
13950 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  b_config() inter
13960 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20  face is used to 
13970 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69  make configurati
13980 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  on.** changes to
13990 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
139a0 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69  nection].  The i
139b0 6e 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69  nterface is simi
139c0 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lar to.** [sqlit
139d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63  e3_config()] exc
139e0 65 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61  ept that the cha
139f0 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20  nges apply to a 
13a00 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62  single.** [datab
13a10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
13a20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68  (specified in th
13a30 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13a40 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63  )..**.** The sec
13a50 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
13a60 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
13a70 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74  g(D,V,...)  is t
13a80 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42  he.** [SQLITE_DB
13a90 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
13aa0 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e   | configuration
13ab0 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65   verb] - an inte
13ac0 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61  ger code .** tha
13ad0 74 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74  t indicates what
13ae0 20 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b   aspect of the [
13af0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13b00 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f  ion] is being co
13b10 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62  nfigured..** Sub
13b20 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74  sequent argument
13b30 73 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  s vary depending
13b40 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72   on the configur
13b50 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a  ation verb..**.*
13b60 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69  * ^Calls to sqli
13b70 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20  te3_db_config() 
13b80 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
13b90 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
13ba0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63  ** the call is c
13bb0 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73  onsidered succes
13bc0 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  sful..*/.SQLITE_
13bd0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
13be0 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
13bf0 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
13c00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13c10 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
13c20 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
13c30 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
13c40 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
13c50 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
13c60 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
13c70 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
13c80 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
13c90 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
13ca0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
13cb0 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
13cc0 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
13cd0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
13ce0 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
13cf0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
13d00 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
13d10 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
13d20 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13d30 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
13d40 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
13d50 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
13d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
13d70 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
13d80 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
13d90 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
13da0 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
13db0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
13dc0 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
13dd0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
13de0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
13df0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
13e00 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
13e10 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
13e20 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
13e30 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
13e40 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
13e50 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
13e60 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
13e70 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
13e80 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
13e90 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
13ea0 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
13eb0 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
13ec0 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
13ed0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
13ee0 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
13ef0 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
13f00 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
13f10 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
13f20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
13f30 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
13f40 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
13f50 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
13f60 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
13f70 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
13f80 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
13f90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
13fa0 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
13fb0 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
13fc0 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
13fd0 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
13fe0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
13ff0 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
14000 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
14010 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
14020 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
14030 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
14040 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
14050 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
14060 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
14070 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
14080 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
14090 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
140a0 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
140b0 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
140c0 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
140d0 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
140e0 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
140f0 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
14100 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
14110 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
14120 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
14130 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
14140 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
14150 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
14160 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
14170 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
14180 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
14190 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
141a0 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
141b0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
141c0 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
141d0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
141e0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
141f0 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
14200 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
14210 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
14220 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
14230 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
14240 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
14250 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
14260 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
14270 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
14280 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
14290 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
142a0 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
142b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
142c0 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
142d0 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
142e0 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
142f0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
14300 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
14310 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
14320 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
14330 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
14340 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
14350 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
14360 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
14370 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
14380 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
14390 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
143a0 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
143b0 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
143c0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
143d0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
143e0 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
143f0 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
14400 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
14410 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
14420 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
14430 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
14440 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
14450 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
14460 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
14470 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
14480 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46  y allocator.  (F
14490 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69  or example,.** i
144a0 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65  t might allocate
144b0 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74   any require mut
144c0 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69  exes or initiali
144d0 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61  ze internal data
144e0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20  .** structures. 
144f0 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d   The xShutdown m
14500 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64  ethod is invoked
14510 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79   (indirectly) by
14520 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
14530 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f  tdown()] and sho
14540 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61  uld deallocate a
14550 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71  ny resources acq
14560 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69  uired.** by xIni
14570 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61  t.  The pAppData
14580 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64   pointer is used
14590 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
145a0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e  ameter to.** xIn
145b0 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e  it and xShutdown
145c0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68  ..**.** SQLite h
145d0 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45  olds the [SQLITE
145e0 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41  _MUTEX_STATIC_MA
145f0 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e  STER] mutex when
14600 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74   it invokes.** t
14610 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c  he xInit method,
14620 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65   so the xInit me
14630 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65  thod need not be
14640 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68   threadsafe.  Th
14650 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d  e.** xShutdown m
14660 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61  ethod is only ca
14670 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  lled from [sqlit
14680 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73  e3_shutdown()] s
14690 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  o it does.** not
146a0 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65   need to be thre
146b0 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20  adsafe either.  
146c0 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65  For all other me
146d0 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a  thods, SQLite.**
146e0 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
146f0 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
14700 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f  MEM] mutex as lo
14710 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51  ng as the.** [SQ
14720 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
14730 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61  TATUS] configura
14740 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74  tion option is t
14750 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a  urned on (which.
14760 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61  ** it is by defa
14770 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20  ult) and so the 
14780 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f  methods are auto
14790 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c  matically serial
147a0 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  ized..** However
147b0 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  , if [SQLITE_CON
147c0 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69  FIG_MEMSTATUS] i
147d0 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e  s disabled, then
147e0 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65   the other.** me
147f0 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68  thods must be th
14800 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65  readsafe or else
14810 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20   make their own 
14820 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72  arrangements for
14830 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f  .** serializatio
14840 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
14850 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b  will never invok
14860 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74  e xInit() more t
14870 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74  han once without
14880 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a   an intervening.
14890 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74  ** call to xShut
148a0 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64  down()..*/.typed
148b0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
148c0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71  3_mem_methods sq
148d0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
148e0 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
148f0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a  3_mem_methods {.
14900 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f    void *(*xMallo
14910 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20  c)(int);        
14920 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63   /* Memory alloc
14930 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a  ation function *
14940 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65  /.  void (*xFree
14950 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20  )(void*);       
14960 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69     /* Free a pri
14970 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  or allocation */
14980 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c  .  void *(*xReal
14990 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b  loc)(void*,int);
149a0 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61    /* Resize an a
149b0 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69  llocation */.  i
149c0 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64  nt (*xSize)(void
149d0 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  *);           /*
149e0 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65   Return the size
149f0 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   of an allocatio
14a00 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f  n */.  int (*xRo
14a10 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20  undup)(int);    
14a20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75        /* Round u
14a30 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74  p request size t
14a40 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  o allocation siz
14a50 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e  e */.  int (*xIn
14a60 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  it)(void*);     
14a70 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c        /* Initial
14a80 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
14a90 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
14aa0 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28  id (*xShutdown)(
14ab0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20  void*);      /* 
14ac0 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65  Deinitialize the
14ad0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
14ae0 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70  r */.  void *pAp
14af0 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20  pData;          
14b00 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e        /* Argumen
14b10 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64  t to xInit() and
14b20 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a   xShutdown() */.
14b30 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
14b40 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  EF: Configuratio
14b50 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59  n Options.** KEY
14b60 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72  WORDS: {configur
14b70 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a  ation option}.**
14b80 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
14b90 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69  nts are the avai
14ba0 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f  lable integer co
14bb0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14bc0 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20  ons that.** can 
14bd0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
14be0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
14bf0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
14c00 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
14c10 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
14c20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14c30 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
14c40 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
14c50 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
14c60 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
14c70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14c80 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
14c90 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
14ca0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
14cb0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
14cc0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
14cd0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
14ce0 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
14cf0 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
14d00 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ked.  The [sqlit
14d10 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
14d20 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75  erface will retu
14d30 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f  rn a.** non-zero
14d40 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
14d50 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20   a discontinued 
14d60 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63  or unsupported c
14d70 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
14d80 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65  ion.** is invoke
14d90 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  d..**.** <dl>.**
14da0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
14db0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20  _SINGLETHREAD]] 
14dc0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
14dd0 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f  G_SINGLETHREAD</
14de0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
14df0 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
14e00 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
14e10 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
14e20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
14e30 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
14e40 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20  Single-thread.  
14e50 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
14e60 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61  it disables.** a
14e70 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20  ll mutexing and 
14e80 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f  puts SQLite into
14e90 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74   a mode where it
14ea0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65   can only be use
14eb0 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65  d.** by a single
14ec0 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53   thread.   ^If S
14ed0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
14ee0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
14ef0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
14f00 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
14f10 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
14f20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
14f30 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f  .** it is not po
14f40 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65  ssible to change
14f50 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20   the [threading 
14f60 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64  mode] from its d
14f70 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20  efault.** value 
14f80 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  of Single-thread
14f90 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33   and so [sqlite3
14fa0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
14fb0 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49  return .** [SQLI
14fc0 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
14fd0 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  led with the SQL
14fe0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
14ff0 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69  ETHREAD.** confi
15000 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
15010 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15020 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
15030 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ITHREAD]] <dt>SQ
15040 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
15050 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20  ITHREAD</dt>.** 
15060 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
15070 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
15080 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
15090 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
150a0 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
150b0 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74  mode] to Multi-t
150c0 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
150d0 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
150e0 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20  les.** mutexing 
150f0 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  on [database con
15100 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72  nection] and [pr
15110 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
15120 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68  ] objects..** Th
15130 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  e application is
15140 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
15150 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63   serializing acc
15160 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62  ess to.** [datab
15170 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
15180 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
15190 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74  tatements].  But
151a0 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a   other mutexes.*
151b0 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f  * are enabled so
151c0 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
151d0 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65  l be safe to use
151e0 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65   in a multi-thre
151f0 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d  aded.** environm
15200 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e  ent as long as n
15210 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74  o two threads at
15220 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
15230 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61   same.** [databa
15240 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61  se connection] a
15250 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
15260 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
15270 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15280 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15290 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
152a0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
152b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
152c0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
152d0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
152e0 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74   set the Multi-t
152f0 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67  hread [threading
15300 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
15310 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15320 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
15330 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
15340 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
15350 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
15360 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66  MULTITHREAD conf
15370 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15380 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
15390 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
153a0 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51  IALIZED]] <dt>SQ
153b0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
153c0 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  ALIZED</dt>.** <
153d0 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
153e0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
153f0 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
15400 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
15410 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
15420 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a  ode] to Serializ
15430 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  ed. In other wor
15440 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20  ds, this option 
15450 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d  enables.** all m
15460 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67  utexes including
15470 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a   the recursive.*
15480 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61  * mutexes on [da
15490 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
154a0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
154b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
154c0 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20  cts..** In this 
154d0 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74  mode (which is t
154e0 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20  he default when 
154f0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
15500 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49  ed with.** [SQLI
15510 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d  TE_THREADSAFE=1]
15520 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  ) the SQLite lib
15530 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66  rary will itself
15540 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73   serialize acces
15550 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73  s.** to [databas
15560 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61  e connections] a
15570 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  nd [prepared sta
15580 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74  tements] so that
15590 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74   the.** applicat
155a0 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75  ion is free to u
155b0 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  se the same [dat
155c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
155d0 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65  ] or the.** same
155e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
155f0 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65  ment] in differe
15600 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68  nt threads at th
15610 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20  e same time..** 
15620 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f  ^If SQLite is co
15630 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74  mpiled with.** t
15640 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41  he [SQLITE_THREA
15650 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54  DSAFE | SQLITE_T
15660 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d  HREADSAFE=0] com
15670 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
15680 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e   then.** it is n
15690 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73  ot possible to s
156a0 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65  et the Serialize
156b0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
156c0 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  e] and.** [sqlit
156d0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
156e0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
156f0 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65  _ERROR] if calle
15700 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51  d with the.** SQ
15710 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
15720 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61  ALIZED configura
15730 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64  tion option.</dd
15740 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
15750 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d  _CONFIG_MALLOC]]
15760 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
15770 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  IG_MALLOC</dt>.*
15780 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
15790 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
157a0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
157b0 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
157c0 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
157d0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
157e0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
157f0 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
15800 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
15810 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
15820 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72   low-level memor
15830 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
15840 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64  tines to be used
15850 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20   in place of.** 
15860 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
15870 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62  ation routines b
15880 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65  uilt into SQLite
15890 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  .)^ ^SQLite make
158a0 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69  s.** its own pri
158b0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
158c0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
158d0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
158e0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a  hods] structure.
158f0 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73  ** before the [s
15900 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15910 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f   call returns.</
15920 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15930 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
15940 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOC]] <dt>SQLITE
15950 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
15960 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  C</dt>.** <dd> ^
15970 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
15980 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
15990 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
159a0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
159b0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
159c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
159d0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
159e0 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
159f0 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  mem_methods].** 
15a00 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
15a10 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
15a20 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
15a30 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15a40 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
15a50 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
15a60 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
15a70 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
15a80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15a90 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
15aa0 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61  th a wrapper tha
15ab0 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65  t simulations me
15ac0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15ad0 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72  failure or.** tr
15ae0 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67  acks memory usag
15af0 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  e, for example. 
15b00 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15b10 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
15b20 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49  TATUS]] <dt>SQLI
15b30 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
15b40 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TUS</dt>.** <dd>
15b50 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61   ^This option ta
15b60 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  kes single argum
15b70 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c  ent of type int,
15b80 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
15b90 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77  a .** boolean, w
15ba0 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20  hich enables or 
15bb0 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c  disables the col
15bc0 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72  lection of memor
15bd0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a  y allocation .**
15be0 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57   statistics. ^(W
15bf0 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  hen memory alloc
15c00 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
15c10 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74   are disabled, t
15c20 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  he .** following
15c30 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
15c40 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70  es become non-op
15c50 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20  erational:.**   
15c60 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  <ul>.**   <li> [
15c70 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
15c80 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  sed()].**   <li>
15c90 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
15ca0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a  _highwater()].**
15cb0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
15cc0 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74  _soft_heap_limit
15cd0 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  64()].**   <li> 
15ce0 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28  [sqlite3_status(
15cf0 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a  )].**   </ul>)^.
15d00 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ** ^Memory alloc
15d10 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
15d20 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20   are enabled by 
15d30 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53  default unless S
15d40 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70  QLite is.** comp
15d50 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  iled with [SQLIT
15d60 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41  E_DEFAULT_MEMSTA
15d70 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20  TUS]=0 in which 
15d80 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61  case memory.** a
15d90 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
15da0 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
15db0 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
15dc0 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
15dd0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
15de0 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATCH]] <dt>SQLIT
15df0 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48  E_CONFIG_SCRATCH
15e00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15e10 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
15e20 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
15e30 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
15e40 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
15e50 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d  for.** scratch m
15e60 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72  emory.  There ar
15e70 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
15e80 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e  s:  A pointer an
15e90 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e   8-byte.** align
15ea0 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ed memory buffer
15eb0 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20   from which the 
15ec0 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
15ed0 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64  ons will be.** d
15ee0 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f  rawn, the size o
15ef0 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61  f each scratch a
15f00 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a  llocation (sz),.
15f10 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d  ** and the maxim
15f20 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72  um number of scr
15f30 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
15f40 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a   (N).  The sz.**
15f50 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
15f60 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  e a multiple of 
15f70 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  16..** The first
15f80 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
15f90 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
15fa0 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64  n 8-byte aligned
15fb0 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74   buffer.** of at
15fc0 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65   least sz*N byte
15fd0 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  s of memory..** 
15fe0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
15ff0 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77   no more than tw
16000 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72  o scratch buffer
16010 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53  s per thread.  S
16020 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65  o.** N should be
16030 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68   set to twice th
16040 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d  e expected maxim
16050 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72  um number of thr
16060 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  eads..** ^SQLite
16070 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75   will never requ
16080 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75  ire a scratch bu
16090 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72  ffer that is mor
160a0 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65  e than 6.** time
160b0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  s the database p
160c0 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51  age size. ^If SQ
160d0 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73  Lite needs needs
160e0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73   additional.** s
160f0 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65  cratch memory be
16100 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
16110 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f  vided by this co
16120 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
16130 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71  on, then .** [sq
16140 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
16150 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20  will be used to 
16160 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72  obtain the memor
16170 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a  y needed.</dd>.*
16180 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16190 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d  NFIG_PAGECACHE]]
161a0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
161b0 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74  IG_PAGECACHE</dt
161c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
161d0 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73  option specifies
161e0 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79   a static memory
161f0 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c   buffer that SQL
16200 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a  ite can use for.
16210 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
16220 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20  page cache with 
16230 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65  the default page
16240 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
16250 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
16260 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73   configuration s
16270 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
16280 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  d if an applicat
16290 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
162a0 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
162b0 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
162c0 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49  d using the SQLI
162d0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
162e0 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65  2 option..** The
162f0 72 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67  re are three arg
16300 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
16310 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72  ption: A pointer
16320 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   to 8-byte align
16330 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68  ed.** memory, th
16340 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70  e size of each p
16350 61 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c  age buffer (sz),
16360 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20   and the number 
16370 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a  of pages (N)..**
16380 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74   The sz argument
16390 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73   should be the s
163a0 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65  ize of the large
163b0 73 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65  st database page
163c0 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20  .** (a power of 
163d0 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20  two between 512 
163e0 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20  and 32768) plus 
163f0 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66  a little extra f
16400 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20  or each.** page 
16410 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61  header.  ^The pa
16420 67 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69  ge header size i
16430 73 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73  s 20 to 40 bytes
16440 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a   depending on.**
16450 20 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74   the host archit
16460 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20  ecture.  ^It is 
16470 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20  harmless, apart 
16480 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20  from the wasted 
16490 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61  memory,.** to ma
164a0 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74  ke sz a little t
164b0 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66  oo large.  The f
164c0 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  irst.** argument
164d0 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f   should point to
164e0 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f   an allocation o
164f0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
16500 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
16510 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
16520 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20   use the memory 
16530 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20  provided by the 
16540 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
16550 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a  o satisfy its.**
16560 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f   memory needs fo
16570 72 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61  r the first N pa
16580 67 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73  ges that it adds
16590 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20   to cache.  ^If 
165a0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61  additional.** pa
165b0 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20  ge cache memory 
165c0 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64  is needed beyond
165d0 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65   what is provide
165e0 64 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e  d by this option
165f0 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
16600 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65   goes to [sqlite
16610 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20  3_malloc()] for 
16620 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73  the additional s
16630 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a  torage space..**
16640 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20   The pointer in 
16650 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
16660 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c  nt must.** be al
16670 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
16680 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  te boundary or s
16690 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
166a0 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  or of SQLite.** 
166b0 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
166c0 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  d.</dd>.**.** [[
166d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
166e0 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  AP]] <dt>SQLITE_
166f0 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e  CONFIG_HEAP</dt>
16700 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
16710 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
16720 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
16730 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
16740 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66  te will use.** f
16750 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79  or all of its dy
16760 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
16770 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65  ocation needs be
16780 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69  yond those provi
16790 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53  ded.** for by [S
167a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
167b0 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54  ATCH] and [SQLIT
167c0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
167d0 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72  HE]..** There ar
167e0 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74  e three argument
167f0 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69  s: An 8-byte ali
16800 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20  gned pointer to 
16810 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  the memory,.** t
16820 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
16830 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  es in the memory
16840 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65   buffer, and the
16850 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
16860 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66  ion size..** ^If
16870 20 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   the first point
16880 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
16890 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c  ointer) is NULL,
168a0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76   then SQLite rev
168b0 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67  erts.** to using
168c0 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d   its default mem
168d0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74  ory allocator (t
168e0 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
168f0 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  () implementatio
16900 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61  n),.** undoing a
16910 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74  ny prior invocat
16920 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43  ion of [SQLITE_C
16930 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20  ONFIG_MALLOC].  
16940 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72  ^If the.** memor
16950 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  y pointer is not
16960 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72   NULL and either
16970 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
16980 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b  MEMSYS3] or.** [
16990 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45  SQLITE_ENABLE_ME
169a0 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e  MSYS5] are defin
169b0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74  ed, then the alt
169c0 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a  ernative memory.
169d0 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ** allocator is 
169e0 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c  engaged to handl
169f0 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73  e all of SQLites
16a00 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16a10 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65  on needs..** The
16a20 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28   first pointer (
16a30 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74  the memory point
16a40 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67  er) must be alig
16a50 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65  ned to an 8-byte
16a60 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20  .** boundary or 
16a70 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76  subsequent behav
16a80 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69  ior of SQLite wi
16a90 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e  ll be undefined.
16aa0 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20  .** The minimum 
16ab0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
16ac0 69 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a  is capped at 2**
16ad0 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76  12. Reasonable v
16ae0 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65  alues.** for the
16af0 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74   minimum allocat
16b00 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a  ion size are 2**
16b10 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c  5 through 2**8.<
16b20 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16b30 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
16b40 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16b50 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a  NFIG_MUTEX</dt>.
16b60 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
16b70 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
16b80 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
16b90 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
16ba0 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
16bb0 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
16bc0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
16bd0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
16be0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
16bf0 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
16c00 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75  ive low-level mu
16c10 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tex routines to 
16c20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
16c30 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f  .** the mutex ro
16c40 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74  utines built int
16c50 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51  o SQLite.)^  ^SQ
16c60 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
16c70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74  y of the.** cont
16c80 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  ent of the [sqli
16c90 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
16ca0 73 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66  s] structure bef
16cb0 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a  ore the call to.
16cc0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
16cd0 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e  ig()] returns. ^
16ce0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
16cf0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
16d00 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
16d10 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
16d20 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
16d30 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
16d40 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
16d50 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
16d60 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
16d70 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
16d80 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
16d90 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
16da0 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
16db0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16dc0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
16dd0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
16de0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
16df0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
16e00 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16e10 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20  NFIG_GETMUTEX]] 
16e20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
16e30 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a  G_GETMUTEX</dt>.
16e40 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
16e50 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
16e60 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
16e70 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
16e80 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
16e90 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
16ea0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
16eb0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
16ec0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75  e.** [sqlite3_mu
16ed0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  tex_methods].** 
16ee0 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c  structure is fil
16ef0 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72  led with the cur
16f00 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d  rently defined m
16f10 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e  utex routines.)^
16f20 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
16f30 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
16f40 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
16f50 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61  ult mutex alloca
16f60 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
16f70 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
16f80 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75  used to track mu
16f90 74 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65  tex usage for pe
16fa0 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f  rformance.** pro
16fb0 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e  filing or testin
16fc0 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20  g, for example. 
16fd0 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
16fe0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
16ff0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
17000 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
17010 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
17020 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
17030 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
17040 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
17050 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
17060 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
17070 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
17080 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
17090 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
170a0 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
170b0 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66  IG_GETMUTEX conf
170c0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
170d0 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20   will.** return 
170e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c  [SQLITE_ERROR].<
170f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
17100 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17110 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  SIDE]] <dt>SQLIT
17120 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
17130 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
17140 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
17150 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
17160 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65  s that determine
17170 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20   the default.** 
17180 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
17190 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73  n for the lookas
171a0 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
171b0 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20  ator on each.** 
171c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
171d0 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73  tion].  The firs
171e0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  t argument is th
171f0 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63  e.** size of eac
17200 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  h lookaside buff
17210 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20  er slot and the 
17220 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75  second is the nu
17230 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
17240 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61   allocated to ea
17250 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
17260 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69  ection.)^  ^(Thi
17270 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
17280 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c  e.** <i>default<
17290 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69  /i> lookaside si
172a0 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  ze. The [SQLITE_
172b0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
172c0 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b  DE].** verb to [
172d0 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
172e0 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64  g()] can be used
172f0 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c   to change the l
17300 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66  ookaside.** conf
17310 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64  iguration on ind
17320 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69  ividual connecti
17330 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ons.)^ </dd>.**.
17340 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17350 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74  IG_PCACHE2]] <dt
17360 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  >SQLITE_CONFIG_P
17370 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
17380 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
17390 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
173a0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
173b0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
173c0 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ** an [sqlite3_p
173d0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
173e0 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62  object.  This ob
173f0 6a 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74  ject specifies t
17400 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
17410 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65  to a custom page
17420 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
17430 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74  ation.)^  ^SQLit
17440 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
17450 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20  f the.** object 
17460 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20  and uses it for 
17470 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
17480 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f  y allocations.</
17490 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
174a0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
174b0 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
174c0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
174d0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
174e0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
174f0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
17500 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
17510 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
17520 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  ** [sqlite3_pcac
17530 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
17540 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
17550 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
17560 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
17570 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
17580 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
17590 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
175a0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
175b0 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  LOG]] <dt>SQLITE
175c0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e  _CONFIG_LOG</dt>
175d0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20 53 51  .** <dd> ^The SQ
175e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
175f0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f  option takes two
17600 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f   arguments: a po
17610 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75  inter to a.** fu
17620 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 63 61  nction with a ca
17630 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f 66 20  ll signature of 
17640 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e  void(*)(void*,in
17650 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20  t,const char*), 
17660 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e 74 65  .** and a pointe
17670 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74  r to void. ^If t
17680 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e  he function poin
17690 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  ter is not NULL,
176a0 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65   it is.** invoke
176b0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f  d by [sqlite3_lo
176c0 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73 73 20  g()] to process 
176d0 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65 76 65  each logging eve
176e0 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
176f0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
17700 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73   is NULL, the [s
17710 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e  qlite3_log()] in
17720 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65 73 20  terface becomes 
17730 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65  a no-op..** ^The
17740 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20 74 68   void pointer th
17750 61 74 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64  at is the second
17760 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c   argument to SQL
17770 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69  ITE_CONFIG_LOG i
17780 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68 72 6f  s.** passed thro
17790 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
177a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
177b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
177c0 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20  fined logger.** 
177d0 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65 76 65  function wheneve
177e0 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f 6e 20  r that function 
177f0 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68  is invoked.  ^Th
17800 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
17810 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67  er to.** the log
17820 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ger function is 
17830 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 66 69  a copy of the fi
17840 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
17850 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
17860 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  ng.** [sqlite3_l
17870 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69  og()] call and i
17880 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 62 65  s intended to be
17890 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d   a [result code]
178a0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e   or an.** [exten
178b0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 5d  ded result code]
178c0 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 70 61  .  ^The third pa
178d0 72 61 6d 65 74 65 72 20 70 61 73 73 65 64 20 74  rameter passed t
178e0 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69 73 0a  o the logger is.
178f0 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65 20 61  ** log message a
17900 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e 67 20  fter formatting 
17910 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  via [sqlite3_snp
17920 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65  rintf()]..** The
17930 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20   SQLite logging 
17940 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74  interface is not
17950 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68 65 20   reentrant; the 
17960 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a  logger function.
17970 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79 20 74  ** supplied by t
17980 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
17990 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61  ust not invoke a
179a0 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
179b0 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c  ace..** In a mul
179c0 74 69 2d 74 68 72 65 61 64 65 64 20 61 70 70 6c  ti-threaded appl
179d0 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61 70 70  ication, the app
179e0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
179f0 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
17a00 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68 72 65  ion must be thre
17a10 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  adsafe. </dd>.**
17a20 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
17a30 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51  FIG_URI]] <dt>SQ
17a40 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a  LITE_CONFIG_URI.
17a50 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f 70 74  ** <dd> This opt
17a60 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17a70 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  le argument of t
17a80 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d  ype int. If non-
17a90 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52  zero, then.** UR
17aa0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
17ab0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20  obally enabled. 
17ac0 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
17ad0 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55   is zero, then U
17ae0 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69  RI handling.** i
17af0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
17b00 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61 6e 64  led. If URI hand
17b10 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
17b20 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69   enabled, all fi
17b30 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65  lenames.** passe
17b40 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  d to [sqlite3_op
17b50 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  en()], [sqlite3_
17b60 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c  open_v2()], [sql
17b70 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f  ite3_open16()] o
17b80 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61  r.** specified a
17b90 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43  s part of [ATTAC
17ba0 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20  H] commands are 
17bb0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
17bc0 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a  RIs, regardless.
17bd0 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ** of whether or
17be0 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45   not the [SQLITE
17bf0 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
17c00 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20  is set when the 
17c10 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
17c20 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
17c30 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61  . If it is globa
17c40 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
17c50 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
17c60 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
17c70 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
17c80 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
17c90 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
17ca0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
17cb0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
17cc0 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75 6c 74  ened. By default
17cd0 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  , URI handling i
17ce0 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69  s globally.** di
17cf0 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61  sabled. The defa
17d00 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65  ult value may be
17d10 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70   changed by comp
17d20 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a  iling with the.*
17d30 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52  * [SQLITE_USE_UR
17d40 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65  I] symbol define
17d50 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d..**.** [[SQLIT
17d60 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d  E_CONFIG_PCACHE]
17d70 5d 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ] [[SQLITE_CONFI
17d80 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a  G_GETPCACHE]].**
17d90 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17da0 49 47 5f 50 43 41 43 48 45 20 61 6e 64 20 53 51  IG_PCACHE and SQ
17db0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
17dc0 43 41 43 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68  CACHE.** <dd> Th
17dd0 65 73 65 20 6f 70 74 69 6f 6e 73 20 61 72 65 20  ese options are 
17de0 6f 62 73 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f  obsolete and sho
17df0 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20  uld not be used 
17e00 62 79 20 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20  by new code..** 
17e10 54 68 65 79 20 61 72 65 20 72 65 74 61 69 6e 65  They are retaine
17e20 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
17e30 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 62 75  compatibility bu
17e40 74 20 61 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73  t are now no-ops
17e50 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ..** </dl>.*/.#d
17e60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17e70 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
17e80 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    1  /* nil */.#
17e90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17ea0 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
17eb0 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     2  /* nil */.
17ec0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17ed0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
17ee0 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f      3  /* nil */
17ef0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17f00 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20  CONFIG_MALLOC   
17f10 20 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74       4  /* sqlit
17f20 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20  e3_mem_methods* 
17f30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17f40 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
17f50 4f 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c  OC     5  /* sql
17f60 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
17f70 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
17f80 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
17f90 43 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76  CH       6  /* v
17fa0 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e  oid*, int sz, in
17fb0 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  t N */.#define S
17fc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
17fd0 45 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a  ECACHE     7  /*
17fe0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20   void*, int sz, 
17ff0 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65  int N */.#define
18000 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48   SQLITE_CONFIG_H
18010 45 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20  EAP          8  
18020 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42  /* void*, int nB
18030 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a  yte, int min */.
18040 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18050 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20  ONFIG_MEMSTATUS 
18060 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61      9  /* boolea
18070 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
18080 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
18090 20 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73          10  /* s
180a0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
180b0 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
180c0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
180d0 45 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20  ETMUTEX     11  
180e0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
180f0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20  _methods* */./* 
18100 70 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54  previously SQLIT
18110 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c  E_CONFIG_CHUNKAL
18120 4c 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20  LOC 12 which is 
18130 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a  now unused. */ .
18140 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18150 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
18160 20 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e     13  /* int in
18170 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
18180 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
18190 45 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e  E       14  /* n
181a0 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
181b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
181c0 54 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f  TPCACHE    15  /
181d0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
181e0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
181f0 5f 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36  _LOG          16
18200 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64    /* xFunc, void
18210 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
18220 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20  ITE_CONFIG_URI  
18230 20 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69          17  /* i
18240 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
18250 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
18260 48 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20  HE2      18  /* 
18270 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
18280 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66  ethods2* */.#def
18290 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
182a0 47 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31  G_GETPCACHE2   1
182b0 39 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  9  /* sqlite3_pc
182c0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a  ache_methods2* *
182d0 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
182e0 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
182f0 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61  ection Configura
18300 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a  tion Options.**.
18310 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
18320 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
18330 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
18340 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
18350 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
18360 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
18370 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
18380 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
18390 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  db_config()] int
183a0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
183b0 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
183c0 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
183d0 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
183e0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
183f0 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
18400 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
18410 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
18420 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
18430 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
18440 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
18450 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
18460 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
18470 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72  g()] to make sur
18480 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61  e that.** the ca
18490 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65  ll worked.  ^The
184a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
184b0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
184c0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
184d0 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
184e0 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
184f0 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
18500 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
18510 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
18520 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
18530 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53  ** <dl>.** <dt>S
18540 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
18550 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a  OOKASIDE</dt>.**
18560 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
18570 6f 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61  on takes three a
18580 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
18590 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
185a0 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b  ne the .** [look
185b0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
185c0 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72  ocator] configur
185d0 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64  ation for the [d
185e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
185f0 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72  on]..** ^The fir
18600 73 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65  st argument (the
18610 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
18620 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f   to [sqlite3_db_
18630 63 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a  config()] is a.*
18640 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d  * pointer to a m
18650 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20  emory buffer to 
18660 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64  use for lookasid
18670 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68  e memory..** ^Th
18680 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18690 20 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54   after the SQLIT
186a0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
186b0 53 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79  SIDE verb.** may
186c0 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63   be NULL in whic
186d0 68 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69  h case SQLite wi
186e0 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a  ll allocate the.
186f0 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66  ** lookaside buf
18700 66 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67  fer itself using
18710 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
18720 28 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64  ()]. ^The second
18730 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
18740 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
18750 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
18760 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68  r slot.  ^The th
18770 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
18780 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
18790 20 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a   slots.  The siz
187a0 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  e of the buffer 
187b0 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
187c0 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72  ument must be gr
187d0 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72  eater than.** or
187e0 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72   equal to the pr
187f0 6f 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63  oduct of the sec
18800 6f 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72  ond and third ar
18810 67 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75  guments.  The bu
18820 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20  ffer.** must be 
18830 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
18840 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20  byte boundary.  
18850 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61  ^If the second a
18860 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51  rgument to.** SQ
18870 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
18880 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61  OKASIDE is not a
18890 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20   multiple of 8, 
188a0 69 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79  it is internally
188b0 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e  .** rounded down
188c0 20 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61   to the next sma
188d0 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ller multiple of
188e0 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61   8.  ^(The looka
188f0 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63  side memory.** c
18900 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
18910 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
18920 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20  ection can only 
18930 62 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20  be changed when 
18940 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  that.** connecti
18950 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e  on is not curren
18960 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73  tly using lookas
18970 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69  ide memory, or i
18980 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a  n other words.**
18990 20 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65   when the "curre
189a0 6e 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e  nt value" return
189b0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
189c0 33 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b  3_db_status](D,[
189d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
189e0 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73  OKASIDE],...) is
189f0 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74   zero..** Any at
18a00 74 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20  tempt to change 
18a10 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
18a20 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69  mory configurati
18a30 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64  on when lookasid
18a40 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69  e.** memory is i
18a50 6e 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65  n use leaves the
18a60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
18a70 6e 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74  nchanged and ret
18a80 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45  urns .** [SQLITE
18a90 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a  _BUSY].)^</dd>.*
18aa0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
18ab0 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
18ac0 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  FKEY</dt>.** <dd
18ad0 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  > ^This option i
18ae0 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65  s used to enable
18af0 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
18b00 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a  enforcement of.*
18b10 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63  * [foreign key c
18b20 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68  onstraints].  Th
18b30 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
18b40 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
18b50 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
18b60 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
18b70 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
18b80 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
18b90 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
18ba0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
18bb0 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72   enable FK enfor
18bc0 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69  cement or negati
18bd0 76 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65  ve to leave FK e
18be0 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e  nforcement.** un
18bf0 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65  changed.  The se
18c00 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
18c10 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
18c20 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
18c30 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
18c40 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
18c50 69 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b  icate whether FK
18c60 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20   enforcement is 
18c70 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c  off or on.** fol
18c80 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c  lowing this call
18c90 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  .  The second pa
18ca0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61  rameter may be a
18cb0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69   NULL pointer, i
18cc0 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20  n.** which case 
18cd0 74 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  the FK enforceme
18ce0 6e 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f  nt setting is no
18cf0 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e  t reported back.
18d00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74   </dd>.**.** <dt
18d10 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
18d20 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c  _ENABLE_TRIGGER<
18d30 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
18d40 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65  is option is use
18d50 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  d to enable or d
18d60 69 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54  isable [CREATE T
18d70 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
18d80 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f  s]..** There sho
18d90 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74  uld be two addit
18da0 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e  ional arguments.
18db0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
18dc0 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74  gument is an int
18dd0 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20  eger which is 0 
18de0 74 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67  to disable trigg
18df0 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ers,.** positive
18e00 20 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67   to enable trigg
18e10 65 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ers or negative 
18e20 74 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74  to leave the set
18e30 74 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a  ting unchanged..
18e40 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61  ** The second pa
18e50 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69  rameter is a poi
18e60 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
18e70 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a  er into which.**
18e80 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72   is written 0 or
18e90 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77   1 to indicate w
18ea0 68 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20  hether triggers 
18eb0 61 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20  are disabled or 
18ec0 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f  enabled.** follo
18ed0 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20  wing this call. 
18ee0 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
18ef0 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e  meter may be a N
18f00 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a  ULL pointer, in.
18f10 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68  ** which case th
18f20 65 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e  e trigger settin
18f30 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
18f40 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
18f50 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
18f60 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f  fine SQLITE_DBCO
18f70 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
18f80 20 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f       1001  /* vo
18f90 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23  id* int int */.#
18fa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
18fb0 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b  CONFIG_ENABLE_FK
18fc0 45 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20  EY     1002  /* 
18fd0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66  int int* */.#def
18fe0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18ff0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
19000 45 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74  ER  1003  /* int
19010 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a   int* */.../*.**
19020 20 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c   CAPI3REF: Enabl
19030 65 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74  e Or Disable Ext
19040 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
19050 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  es.**.** ^The sq
19060 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
19070 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f  esult_codes() ro
19080 75 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72  utine enables or
19090 20 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a   disables the.**
190a0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
190b0 74 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65  t codes] feature
190c0 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65   of SQLite. ^The
190d0 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
190e0 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69  .** codes are di
190f0 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  sabled by defaul
19100 74 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c  t for historical
19110 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
19120 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
19130 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
19140 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
19150 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e  sqlite3*, int on
19160 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  off);../*.** CAP
19170 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e 73 65  I3REF: Last Inse
19180 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e  rt Rowid.**.** ^
19190 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20 61 6e  Each entry in an
191a0 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20 68 61   SQLite table ha
191b0 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69  s a unique 64-bi
191c0 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65  t signed.** inte
191d0 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74  ger key called t
191e0 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77  he [ROWID | "row
191f0 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64  id"]. ^The rowid
19200 20 69 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c   is always avail
19210 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e  able.** as an un
19220 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20  declared column 
19230 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44  named ROWID, OID
19240 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20  , or _ROWID_ as 
19250 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a  long as those.**
19260 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61   names are not a
19270 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c  lso used by expl
19280 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20  icitly declared 
19290 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20  columns. ^If.** 
192a0 74 68 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  the table has a 
192b0 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b  column of type [
192c0 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52 59 20  INTEGER PRIMARY 
192d0 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63  KEY] then that c
192e0 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74  olumn.** is anot
192f0 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68  her alias for th
19300 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e  e rowid..**.** ^
19310 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
19320 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64 5d  urns the [rowid]
19330 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63   of the most rec
19340 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ent.** successfu
19350 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20  l [INSERT] into 
19360 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72 6f  the database fro
19370 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  m the [database 
19380 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69  connection].** i
19390 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
193a0 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66 20 53 51  ment.  ^As of SQ
193b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37  Lite version 3.7
193c0 2e 37 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .7, this routine
193d0 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20 74 68 65  s.** records the
193e0 20 6c 61 73 74 20 69 6e 73 65 72 74 20 72 6f 77   last insert row
193f0 69 64 20 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e  id of both ordin
19400 61 72 79 20 74 61 62 6c 65 73 20 61 6e 64 20 5b  ary tables and [
19410 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e  virtual tables].
19420 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75 63 63 65  .** ^If no succe
19430 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a  ssful [INSERT]s.
19440 2a 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63  ** have ever occ
19450 75 72 72 65 64 20 6f 6e 20 74 68 61 74 20 64 61  urred on that da
19460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19470 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65 74 75 72  n, zero is retur
19480 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ned..**.** ^(If 
19490 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75  an [INSERT] occu
194a0 72 73 20 77 69 74 68 69 6e 20 61 20 74 72 69 67  rs within a trig
194b0 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20  ger or within a 
194c0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a  [virtual table].
194d0 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  ** method, then 
194e0 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c  this routine wil
194f0 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f  l return the [ro
19500 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65  wid] of the inse
19510 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c  rted.** row as l
19520 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69 67 67  ong as the trigg
19530 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
19540 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75  ble method is ru
19550 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e  nning..** But on
19560 63 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  ce the trigger o
19570 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
19580 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65  method ends, the
19590 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
195a0 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74  .** by this rout
195b0 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f 20 77  ine reverts to w
195c0 68 61 74 20 69 74 20 77 61 73 20 62 65 66 6f 72  hat it was befor
195d0 65 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72  e the trigger or
195e0 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c   virtual.** tabl
195f0 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29  e method began.)
19600 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53  ^.**.** ^An [INS
19610 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20  ERT] that fails 
19620 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61  due to a constra
19630 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73  int violation is
19640 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73   not a.** succes
19650 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e  sful [INSERT] an
19660 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  d does not chang
19670 65 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  e the value retu
19680 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20  rned by this.** 
19690 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20  routine.  ^Thus 
196a0 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20  INSERT OR FAIL, 
196b0 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45  INSERT OR IGNORE
196c0 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c  , INSERT OR ROLL
196d0 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53  BACK,.** and INS
196e0 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b  ERT OR ABORT mak
196f0 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20  e no changes to 
19700 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
19710 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   of this.** rout
19720 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72 20 69  ine when their i
19730 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20  nsertion fails. 
19740 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f   ^(When INSERT O
19750 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63  R REPLACE.** enc
19760 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72  ounters a constr
19770 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20  aint violation, 
19780 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c  it does not fail
19790 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54  .  The.** INSERT
197a0 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f   continues to co
197b0 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64  mpletion after d
197c0 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61  eleting rows tha
197d0 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20  t caused.** the 
197e0 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c  constraint probl
197f0 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20  em so INSERT OR 
19800 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77  REPLACE will alw
19810 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68  ays change.** th
19820 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
19830 66 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65  f this interface
19840 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74  .)^.**.** ^For t
19850 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74  he purposes of t
19860 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20  his routine, an 
19870 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73  [INSERT] is cons
19880 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20  idered to.** be 
19890 73 75 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20  successful even 
198a0 69 66 20 69 74 20 69 73 20 73 75 62 73 65 71 75  if it is subsequ
198b0 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  ently rolled bac
198c0 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  k..**.** This fu
198d0 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73  nction is access
198e0 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74  ible to SQL stat
198f0 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a  ements via the.*
19900 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  * [last_insert_r
19910 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74  owid() SQL funct
19920 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
19930 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
19940 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20   performs a new 
19950 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20  [INSERT] on the 
19960 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65  same.** database
19970 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c   connection whil
19980 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c  e the [sqlite3_l
19990 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
199a0 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ()].** function 
199b0 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74  is running and t
199c0 68 75 73 20 63 68 61 6e 67 65 73 20 74 68 65 20  hus changes the 
199d0 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
199e0 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  id],.** then the
199f0 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20   value returned 
19a00 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  by [sqlite3_last
19a10 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19a20 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74   is.** unpredict
19a30 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e  able and might n
19a40 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65 72 20  ot equal either 
19a50 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e  the old or the n
19a60 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72  ew.** last inser
19a70 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51  t [rowid]..*/.SQ
19a80 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
19a90 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c  _int64 sqlite3_l
19aa0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
19ab0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
19ac0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75  ** CAPI3REF: Cou
19ad0 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66  nt The Number Of
19ae0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
19af0 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
19b00 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
19b10 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61  number of databa
19b20 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65 72  se rows that wer
19b30 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20  e changed.** or 
19b40 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65  inserted or dele
19b50 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20  ted by the most 
19b60 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
19b70 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
19b80 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61  .** on the [data
19b90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19ba0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
19bb0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
19bc0 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61  r..** ^(Only cha
19bd0 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64 69  nges that are di
19be0 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65 64  rectly specified
19bf0 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d   by the [INSERT]
19c00 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f  , [UPDATE],.** o
19c10 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65  r [DELETE] state
19c20 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64  ment are counted
19c30 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68 61  .  Auxiliary cha
19c40 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a  nges caused by.*
19c50 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66  * triggers or [f
19c60 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
19c70 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  ns] are not coun
19c80 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a  ted.)^ Use the.*
19c90 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  * [sqlite3_total
19ca0 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63  _changes()] func
19cb0 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65  tion to find the
19cc0 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
19cd0 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c   changes.** incl
19ce0 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61  uding changes ca
19cf0 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72 73  used by triggers
19d00 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79   and foreign key
19d10 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20   actions..**.** 
19d20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69  ^Changes to a vi
19d30 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d 75  ew that are simu
19d40 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53  lated by an [INS
19d50 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
19d60 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e  .** are not coun
19d70 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20  ted.  Only real 
19d80 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72  table changes ar
19d90 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a  e counted..**.**
19da0 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65   ^(A "row change
19db0 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f  " is a change to
19dc0 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66   a single row of
19dd0 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a   a single table.
19de0 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e 20  ** caused by an 
19df0 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20  INSERT, DELETE, 
19e00 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65 6d  or UPDATE statem
19e10 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a  ent.  Rows that.
19e20 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20 61  ** are changed a
19e30 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20 6f  s side effects o
19e40 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  f [REPLACE] cons
19e50 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f  traint resolutio
19e60 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20  n,.** rollback, 
19e70 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
19e80 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20  , [DROP TABLE], 
19e90 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a  or by any other.
19ea0 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f  ** mechanisms do
19eb0 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69   not count as di
19ec0 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
19ed0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69  .)^.**.** A "tri
19ee0 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73  gger context" is
19ef0 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63   a scope of exec
19f00 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e  ution that begin
19f10 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69  s and.** ends wi
19f20 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f 66  th the script of
19f30 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47 47   a [CREATE TRIGG
19f40 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a  ER | trigger]. .
19f50 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74  ** Most SQL stat
19f60 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76  ements are.** ev
19f70 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65 20  aluated outside 
19f80 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20  of any trigger. 
19f90 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74 6f   This is the "to
19fa0 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67  p level".** trig
19fb0 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66  ger context.  If
19fc0 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65 73   a trigger fires
19fd0 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65   from the top le
19fe0 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72  vel, a.** new tr
19ff0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73  igger context is
1a000 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65   entered for the
1a010 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61   duration of tha
1a020 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72  t one.** trigger
1a030 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20 63  .  Subtriggers c
1a040 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74  reate subcontext
1a050 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72 61  s for their dura
1a060 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  tion..**.** ^Cal
1a070 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78  ling [sqlite3_ex
1a080 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ec()] or [sqlite
1a090 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72 73  3_step()] recurs
1a0a0 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ively does.** no
1a0b0 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20 74  t create a new t
1a0c0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
1a0d0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1a0e0 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
1a0f0 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63   number of direc
1a100 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e  t row changes in
1a110 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63   the.** most rec
1a120 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
1a130 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74  TE, or DELETE st
1a140 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74  atement within t
1a150 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67  he same.** trigg
1a160 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a  er context..**.*
1a170 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61  * ^Thus, when ca
1a180 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f  lled from the to
1a190 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75  p level, this fu
1a1a0 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1a1b0 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
1a1c0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d  changes in the m
1a1d0 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
1a1e0 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1a1f0 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73  LETE.** that als
1a200 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74 68  o occurred at th
1a210 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28  e top level.  ^(
1a220 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  Within the body 
1a230 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a  of a trigger,.**
1a240 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61   the sqlite3_cha
1a250 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63 65  nges() interface
1a260 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74   can be called t
1a270 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65  o find the numbe
1a280 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20  r of.** changes 
1a290 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  in the most rece
1a2a0 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49  ntly completed I
1a2b0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
1a2c0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74  r DELETE.** stat
1a2d0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
1a2e0 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d   body of the sam
1a2f0 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f  e trigger..** Ho
1a300 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65  wever, the numbe
1a310 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20  r returned does 
1a320 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
1a330 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ges.** caused by
1a340 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69 6e   subtriggers sin
1a350 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74 68  ce those have th
1a360 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e  eir own context.
1a370 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )^.**.** See als
1a380 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74  o the [sqlite3_t
1a390 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
1a3a0 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
1a3b0 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
1a3c0 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
1a3d0 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c  e [changes() SQL
1a3e0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
1a3f0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
1a400 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
1a410 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
1a420 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a430 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
1a440 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
1a450 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
1a460 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  n the value retu
1a470 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65  rned.** is unpre
1a480 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
1a490 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
1a4a0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1a4b0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73  qlite3_changes(s
1a4c0 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1a4d0 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c   CAPI3REF: Total
1a4e0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
1a4f0 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
1a500 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
1a510 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1a520 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20   of row changes 
1a530 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52  caused by [INSER
1a540 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20  T],.** [UPDATE] 
1a550 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
1a560 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65  ements since the
1a570 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1a580 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65  ction] was opene
1a590 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e  d..** ^(The coun
1a5a0 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  t returned by sq
1a5b0 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
1a5c0 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61  ges() includes a
1a5d0 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72  ll changes.** fr
1a5e0 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54  om all [CREATE T
1a5f0 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
1a600 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63  ] contexts and c
1a610 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a  hanges made by.*
1a620 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  * [foreign key a
1a630 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72  ctions]. However
1a640 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64  ,.** the count d
1a650 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1a660 63 68 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20  changes used to 
1a670 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41  implement [REPLA
1a680 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c  CE] constraints,
1a690 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73  .** do rollbacks
1a6a0 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73   or ABORT proces
1a6b0 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54  sing, or [DROP T
1a6c0 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67  ABLE] processing
1a6d0 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20  .  The.** count 
1a6e0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
1a6f0 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74   rows of views t
1a700 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53  hat fire an [INS
1a710 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d  TEAD OF trigger]
1a720 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74  ,.** though if t
1a730 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72  he INSTEAD OF tr
1a740 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e  igger makes chan
1a750 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20  ges of its own, 
1a760 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a  those changes .*
1a770 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e  * are counted.)^
1a780 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1a790 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1a7a0 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73   function counts
1a7b0 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 73 20   the changes as 
1a7c0 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73  soon as.** the s
1a7d0 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61  tatement that ma
1a7e0 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70  kes them is comp
1a7f0 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68 65 20  leted (when the 
1a800 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  statement handle
1a810 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f  .** is passed to
1a820 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
1a830 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66  )] or [sqlite3_f
1a840 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a  inalize()])..**.
1a850 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
1a860 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73  [sqlite3_changes
1a870 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
1a880 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
1a890 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
1a8a0 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61  d the [total_cha
1a8b0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
1a8c0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
1a8d0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
1a8e0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
1a8f0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
1a900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1a910 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
1a920 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  _total_changes()
1a930 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  ] is running the
1a940 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72  n the value.** r
1a950 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65  eturned is unpre
1a960 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74  dictable and not
1a970 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a   meaningful..*/.
1a980 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1a990 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
1a9a0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
1a9b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1a9c0 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f 6e   Interrupt A Lon
1a9d0 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a  g-Running Query.
1a9e0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
1a9f0 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79 20  tion causes any 
1aa00 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73 65  pending database
1aa10 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61 62   operation to ab
1aa20 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72  ort and.** retur
1aa30 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65 73  n at its earlies
1aa40 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20 54  t opportunity. T
1aa50 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 74  his routine is t
1aa60 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c  ypically.** call
1aa70 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20 74  ed in response t
1aa80 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e 20  o a user action 
1aa90 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e 67  such as pressing
1aaa0 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20   "Cancel".** or 
1aab0 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68 65  Ctrl-C where the
1aac0 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c 6f   user wants a lo
1aad0 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74 69  ng query operati
1aae0 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d  on to halt.** im
1aaf0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  mediately..**.**
1ab00 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f 20   ^It is safe to 
1ab10 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
1ab20 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64 20  e from a thread 
1ab30 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 74  different from t
1ab40 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68 61  he.** thread tha
1ab50 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 72  t is currently r
1ab60 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  unning the datab
1ab70 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20  ase operation.  
1ab80 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74  But it.** is not
1ab90 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68   safe to call th
1aba0 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1abb0 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
1abc0 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20  ection] that.** 
1abd0 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67  is closed or mig
1abe0 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65 20  ht close before 
1abf0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1ac00 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a  t() returns..**.
1ac10 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70  ** ^If an SQL op
1ac20 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79 20  eration is very 
1ac30 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64 20  nearly finished 
1ac40 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65 6e  at the time when
1ac50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  .** sqlite3_inte
1ac60 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c 65  rrupt() is calle
1ac70 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68 74  d, then it might
1ac80 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70 70   not have an opp
1ac90 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62  ortunity.** to b
1aca0 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 6e  e interrupted an
1acb0 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75 65  d might continue
1acc0 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a   to completion..
1acd0 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70  **.** ^An SQL op
1ace0 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73 20  eration that is 
1acf0 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c 6c  interrupted will
1ad00 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1ad10 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e  INTERRUPT]..** ^
1ad20 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70 74  If the interrupt
1ad30 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e  ed SQL operation
1ad40 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20 55   is an INSERT, U
1ad50 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
1ad60 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73 69  .** that is insi
1ad70 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74  de an explicit t
1ad80 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e  ransaction, then
1ad90 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61 6e   the entire tran
1ada0 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20  saction.** will 
1adb0 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61  be rolled back a
1adc0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a  utomatically..**
1add0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1ade0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63 61  _interrupt(D) ca
1adf0 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74 20  ll is in effect 
1ae00 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e  until all curren
1ae10 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53  tly running.** S
1ae20 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e  QL statements on
1ae30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1ae40 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74  ction] D complet
1ae50 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c  e.  ^Any new SQL
1ae60 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
1ae70 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
1ae80 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65  after the sqlite
1ae90 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
1aea0 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74 68  ll and before th
1aeb0 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74  e .** running st
1aec0 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65 73  atements reaches
1aed0 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72 72   zero are interr
1aee0 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65 79  upted as if they
1aef0 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e   had been.** run
1af00 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74 68  ning prior to th
1af10 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1af20 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65  upt() call.  ^Ne
1af30 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  w SQL statements
1af40 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1af50 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 72  rted after the r
1af60 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  unning statement
1af70 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20 7a   count reaches z
1af80 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65  ero are.** not e
1af90 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20 73  ffected by the s
1afa0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1afb0 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  ()..** ^A call t
1afc0 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  o sqlite3_interr
1afd0 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63 75  upt(D) that occu
1afe0 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61 72  rs when there ar
1aff0 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  e no running.** 
1b000 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69  SQL statements i
1b010 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61  s a no-op and ha
1b020 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20 53  s no effect on S
1b030 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1b040 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1b050 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69  d after the sqli
1b060 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1b070 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  call returns..**
1b080 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61 62  .** If the datab
1b090 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
1b0a0 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71 6c  loses while [sql
1b0b0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1b0c0 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20  ].** is running 
1b0d0 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73 20  then bad things 
1b0e0 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70  will likely happ
1b0f0 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  en..*/.SQLITE_AP
1b100 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  I void sqlite3_i
1b110 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
1b120 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1b130 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
1b140 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
1b150 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
1b160 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1b170 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
1b180 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
1b190 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
1b1a0 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
1b1b0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
1b1c0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
1b1d0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
1b1e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
1b1f0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
1b200 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
1b210 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
1b220 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
1b230 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
1b240 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
1b250 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
1b260 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
1b270 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
1b280 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
1b290 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
1b2a0 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
1b2b0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
1b2c0 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
1b2d0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
1b2e0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
1b2f0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
1b300 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
1b310 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
1b320 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
1b330 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
1b340 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
1b350 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
1b360 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
1b370 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
1b380 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
1b390 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
1b3a0 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
1b3b0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
1b3c0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
1b3d0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
1b3e0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
1b3f0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
1b400 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
1b410 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
1b420 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
1b430 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
1b440 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
1b450 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
1b460 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
1b470 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
1b480 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
1b490 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
1b4a0 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
1b4b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
1b4c0 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
1b4d0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
1b4e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
1b4f0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
1b500 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
1b510 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
1b520 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
1b530 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
1b540 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
1b550 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
1b560 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
1b570 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
1b580 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1b590 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
1b5a0 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
1b5b0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
1b5c0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
1b5d0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
1b5e0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
1b5f0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
1b600 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
1b610 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
1b620 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
1b630 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
1b640 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
1b650 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1b660 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
1b670 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
1b680 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
1b690 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
1b6a0 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
1b6b0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1b6c0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1b6d0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
1b6e0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1b6f0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
1b700 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
1b710 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1b720 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
1b730 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
1b740 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
1b750 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
1b760 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
1b770 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1b780 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
1b790 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 29  const char *sql)
1b7a0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
1b7b0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
1b7c0 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
1b7d0 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
1b7e0 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
1b7f0 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
1b800 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
1b810 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54   Errors.**.** ^T
1b820 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
1b830 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1b840 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
1b850 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
1b860 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
1b870 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
1b880 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
1b890 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  le that another 
1b8a0 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
1b8b0 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
1b8c0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
1b8d0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1b8e0 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
1b8f0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
1b900 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
1b910 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
1b920 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
1b930 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
1b940 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
1b950 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1b960 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
1b970 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
1b980 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
1b990 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
1b9a0 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
1b9b0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1b9c0 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
1b9d0 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
1b9e0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
1b9f0 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
1ba00 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
1ba10 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
1ba20 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
1ba30 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
1ba40 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
1ba50 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
1ba60 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
1ba70 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
1ba80 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1ba90 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
1baa0 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
1bab0 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
1bac0 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
1bad0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
1bae0 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
1baf0 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
1bb00 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
1bb10 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
1bb20 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
1bb30 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
1bb40 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
1bb50 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49   returned..** ^I
1bb60 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
1bb70 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1bb80 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
1bb90 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
1bba0 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
1bbb0 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
1bbc0 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
1bbd0 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
1bbe0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
1bbf0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
1bc00 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
1bc10 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
1bc20 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
1bc30 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
1bc40 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
1bc50 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
1bc60 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
1bc70 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
1bc80 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
1bc90 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
1bca0 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
1bcb0 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
1bcc0 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b  TE_BUSY].** or [
1bcd0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
1bce0 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66  CKED] instead of
1bcf0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
1bd00 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
1bd10 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
1bd20 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
1bd30 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
1bd40 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
1bd50 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
1bd60 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1bd70 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
1bd80 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
1bd90 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
1bda0 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
1bdb0 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
1bdc0 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
1bdd0 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
1bde0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
1bdf0 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
1be00 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
1be10 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1be20 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
1be30 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
1be40 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
1be50 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
1be60 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1be70 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
1be80 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
1be90 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
1bea0 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
1beb0 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
1bec0 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
1bed0 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
1bee0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
1bef0 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
1bf00 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
1bf10 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
1bf20 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
1bf30 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1bf40 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
1bf50 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
1bf60 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
1bf70 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
1bf80 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
1bf90 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
1bfa0 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
1bfb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
1bfc0 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
1bfd0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
1bfe0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
1bff0 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
1c000 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
1c010 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
1c020 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
1c030 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
1c040 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
1c050 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
1c060 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
1c070 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
1c080 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
1c090 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
1c0a0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1c0b0 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
1c0c0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
1c0d0 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
1c0e0 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
1c0f0 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
1c100 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
1c110 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
1c120 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
1c130 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
1c140 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73  ders.  ^If it is
1c150 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
1c160 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
1c170 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
1c180 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
1c190 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
1c1a0 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
1c1b0 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
1c1c0 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
1c1d0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
1c1e0 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
1c1f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
1c200 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
1c210 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
1c220 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69  _BLOCKED].  ^Thi
1c230 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
1c240 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
1c250 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
1c260 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
1c270 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
1c280 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
1c290 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
1c2a0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
1c2b0 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
1c2c0 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
1c2d0 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
1c2e0 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
1c2f0 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
1c300 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
1c310 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  rtant..**.** ^(T
1c320 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1c330 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1c340 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
1c350 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
1c360 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c370 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
1c380 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
1c390 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
1c3a0 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
1c3b0 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
1c3c0 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
1c3d0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1c3e0 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20  )].** will also 
1c3f0 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65  set or clear the
1c400 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1c410 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
1c420 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
1c430 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
1c440 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
1c450 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
1c460 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1c470 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
1c480 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73   handler.  Any s
1c490 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
1c4a0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
1c4b0 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
1c4c0 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
1c4d0 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
1c4e0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
1c4f0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
1c500 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1c510 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
1c520 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1c530 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  er..*/.SQLITE_AP
1c540 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75  I int sqlite3_bu
1c550 73 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  sy_handler(sqlit
1c560 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64  e3*, int(*)(void
1c570 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a  *,int), void*);.
1c580 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c590 20 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65   Set A Busy Time
1c5a0 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  out.**.** ^This 
1c5b0 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b  routine sets a [
1c5c0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1c5d0 64 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64  dler | busy hand
1c5e0 6c 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73  ler] that sleeps
1c5f0 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66  .** for a specif
1c600 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69  ied amount of ti
1c610 6d 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20  me when a table 
1c620 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65  is locked.  ^The
1c630 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c   handler.** will
1c640 20 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20   sleep multiple 
1c650 74 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c  times until at l
1c660 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73  east "ms" millis
1c670 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69  econds of sleepi
1c680 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d  ng.** have accum
1c690 75 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20  ulated.  ^After 
1c6a0 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1c6b0 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1c6c0 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68  eeping,.** the h
1c6d0 61 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30  andler returns 0
1c6e0 20 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73   which causes [s
1c6f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74  qlite3_step()] t
1c700 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  o return.** [SQL
1c710 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
1c720 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
1c730 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ED]..**.** ^Call
1c740 69 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ing this routine
1c750 20 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e   with an argumen
1c760 74 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65  t less than or e
1c770 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20  qual to zero.** 
1c780 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75  turns off all bu
1c790 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a  sy handlers..**.
1c7a0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
1c7b0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
1c7c0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72  busy handler for
1c7d0 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a   a particular.**
1c7e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
1c7f0 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67  ction] any any g
1c800 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66  iven moment.  If
1c810 20 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61   another busy ha
1c820 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66  ndler.** was def
1c830 69 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71  ined  (using [sq
1c840 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
1c850 65 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20  er()]) prior to 
1c860 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20  calling.** this 
1c870 72 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74  routine, that ot
1c880 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
1c890 20 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a   is cleared.)^.*
1c8a0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
1c8b0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
1c8c0 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
1c8d0 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
1c8e0 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
1c8f0 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
1c900 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
1c910 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  es.**.** This is
1c920 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
1c930 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
1c940 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
1c950 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
1c960 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
1c970 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
1c980 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
1c990 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
1c9a0 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
1c9b0 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
1c9c0 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
1c9d0 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
1c9e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
1c9f0 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
1ca00 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
1ca10 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
1ca20 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
1ca30 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
1ca40 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
1ca50 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
1ca60 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
1ca70 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
1ca80 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
1ca90 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
1caa0 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
1cab0 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
1cac0 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
1cad0 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
1cae0 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
1caf0 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
1cb00 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
1cb10 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
1cb20 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
1cb30 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
1cb40 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
1cb50 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
1cb60 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
1cb70 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
1cb80 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
1cb90 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
1cba0 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
1cbb0 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
1cbc0 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
1cbd0 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
1cbe0 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
1cbf0 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
1cc00 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
1cc10 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
1cc20 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
1cc30 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
1cc40 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
1cc50 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
1cc60 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
1cc70 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
1cc80 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
1cc90 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
1cca0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
1ccb0 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
1ccc0 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
1ccd0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
1cce0 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
1ccf0 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1cd00 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
1cd10 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
1cd20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1cd30 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
1cd40 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
1cd50 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
1cd60 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
1cd70 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
1cd80 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
1cd90 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
1cda0 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
1cdb0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
1cdc0 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
1cdd0 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
1cde0 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
1cdf0 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
1ce00 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
1ce10 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1ce20 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1ce30 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
1ce40 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
1ce50 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
1ce60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1ce70 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
1ce80 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
1ce90 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
1cea0 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
1ceb0 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
1cec0 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
1ced0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1cee0 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
1cef0 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
1cf00 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
1cf10 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
1cf20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
1cf30 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
1cf40 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
1cf50 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
1cf60 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
1cf70 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
1cf80 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
1cf90 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
1cfa0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1cfb0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
1cfc0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1cfd0 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
1cfe0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1cff0 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
1d000 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1d010 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
1d020 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
1d030 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
1d040 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
1d050 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
1d060 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
1d070 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d080 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
1d090 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1d0a0 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
1d0b0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1d0c0 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
1d0d0 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
1d0e0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
1d0f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1d100 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
1d110 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
1d120 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
1d130 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
1d140 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
1d150 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
1d160 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
1d170 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
1d180 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
1d190 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
1d1a0 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
1d1b0 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
1d1c0 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
1d1d0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
1d1e0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
1d1f0 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
1d200 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
1d210 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
1d220 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
1d230 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
1d240 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
1d250 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
1d260 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
1d270 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
1d280 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
1d290 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
1d2a0 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
1d2b0 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
1d2c0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
1d2d0 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
1d2e0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
1d2f0 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
1d300 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
1d310 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
1d320 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
1d330 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
1d340 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
1d350 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
1d360 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
1d370 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
1d380 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
1d390 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
1d3a0 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
1d3b0 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
1d3c0 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
1d3d0 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
1d3e0 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
1d3f0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1d400 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
1d410 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
1d420 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
1d430 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
1d440 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
1d450 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
1d460 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
1d470 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
1d480 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
1d490 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
1d4a0 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
1d4b0 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
1d4c0 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
1d4d0 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
1d4e0 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
1d4f0 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
1d500 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
1d510 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
1d520 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
1d530 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
1d540 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  rmsg()]..*/.SQLI
1d550 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1d560 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20  e3_get_table(.  
1d570 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
1d580 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e        /* An open
1d590 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
1d5a0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c  onst char *zSql,
1d5b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62       /* SQL to b
1d5c0 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20  e evaluated */. 
1d5d0 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75   char ***pazResu
1d5e0 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74  lt,    /* Result
1d5f0 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a  s of the query *
1d600 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20  /.  int *pnRow, 
1d610 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d            /* Num
1d620 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f  ber of result ro
1d630 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  ws written here 
1d640 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75  */.  int *pnColu
1d650 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75  mn,        /* Nu
1d660 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63  mber of result c
1d670 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68  olumns written h
1d680 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ere */.  char **
1d690 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f  pzErrmsg       /
1d6a0 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
1d6b0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53  ten here */.);.S
1d6c0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1d6d0 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1d6e0 65 28 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29  e(char **result)
1d6f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1d700 46 3a 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72  F: Formatted Str
1d710 69 6e 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e  ing Printing Fun
1d720 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1d730 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
1d740 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74  work-alikes of t
1d750 68 65 20 22 70 72 69 6e 74 66 28 29 22 20 66 61  he "printf()" fa
1d760 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e  mily of function
1d770 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74  s.** from the st
1d780 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79  andard C library
1d790 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d7a0 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61  ite3_mprintf() a
1d7b0 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  nd sqlite3_vmpri
1d7c0 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77  ntf() routines w
1d7d0 72 69 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65  rite their.** re
1d7e0 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72  sults into memor
1d7f0 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
1d800 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1d810 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e  )]..** The strin
1d820 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 74  gs returned by t
1d830 68 65 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65  hese two routine
1d840 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72  s should be.** r
1d850 65 6c 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69  eleased by [sqli
1d860 74 65 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42  te3_free()].  ^B
1d870 6f 74 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74  oth routines ret
1d880 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  urn a.** NULL po
1d890 69 6e 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65  inter if [sqlite
1d8a0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75  3_malloc()] is u
1d8b0 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74  nable to allocat
1d8c0 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f  e enough.** memo
1d8d0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72  ry to hold the r
1d8e0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e  esulting string.
1d8f0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
1d900 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20  ite3_snprintf() 
1d910 72 6f 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c  routine is simil
1d920 61 72 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28  ar to "snprintf(
1d930 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73  )" from.** the s
1d940 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
1d950 79 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 69  y.  The result i
1d960 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  s written into t
1d970 68 65 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70  he.** buffer sup
1d980 70 6c 69 65 64 20 61 73 20 74 68 65 20 73 65 63  plied as the sec
1d990 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 77 68  ond parameter wh
1d9a0 6f 73 65 20 73 69 7a 65 20 69 73 20 67 69 76 65  ose size is give
1d9b0 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73  n by.** the firs
1d9c0 74 20 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74  t parameter. Not
1d9d0 65 20 74 68 61 74 20 74 68 65 20 6f 72 64 65 72  e that the order
1d9e0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74   of the.** first
1d9f0 20 74 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20   two parameters 
1da00 69 73 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d  is reversed from
1da10 20 73 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20   snprintf().)^  
1da20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69  This is an.** hi
1da30 73 74 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e  storical acciden
1da40 74 20 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65  t that cannot be
1da50 20 66 69 78 65 64 20 77 69 74 68 6f 75 74 20 62   fixed without b
1da60 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77  reaking.** backw
1da70 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
1da80 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f  ty.  ^(Note also
1da90 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e   that sqlite3_sn
1daa0 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75  printf().** retu
1dab0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
1dac0 20 69 74 73 20 62 75 66 66 65 72 20 69 6e 73 74   its buffer inst
1dad0 65 61 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65  ead of the numbe
1dae0 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65  r of.** characte
1daf0 72 73 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74  rs actually writ
1db00 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66  ten into the buf
1db10 66 65 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74  fer.)^  We admit
1db20 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d   that.** the num
1db30 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
1db40 73 20 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20  s written would 
1db50 62 65 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c  be a more useful
1db60 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
1db70 20 62 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63   but we cannot c
1db80 68 61 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d  hange the implem
1db90 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
1dba0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
1dbb0 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72  * now without br
1dbc0 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69  eaking compatibi
1dbd0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  lity..**.** ^As 
1dbe0 6c 6f 6e 67 20 61 73 20 74 68 65 20 62 75 66 66  long as the buff
1dbf0 65 72 20 73 69 7a 65 20 69 73 20 67 72 65 61 74  er size is great
1dc00 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71  er than zero, sq
1dc10 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1dc20 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74  .** guarantees t
1dc30 68 61 74 20 74 68 65 20 62 75 66 66 65 72 20 69  hat the buffer i
1dc40 73 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  s always zero-te
1dc50 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
1dc60 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
1dc70 65 72 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f  er "n" is the to
1dc80 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20  tal size of the 
1dc90 62 75 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e  buffer, includin
1dca0 67 20 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74  g space for.** t
1dcb0 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
1dcc0 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67  or.  So the long
1dcd0 65 73 74 20 73 74 72 69 6e 67 20 74 68 61 74 20  est string that 
1dce0 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c  can be completel
1dcf0 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c  y.** written wil
1dd00 6c 20 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74  l be n-1 charact
1dd10 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ers..**.** ^The 
1dd20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74  sqlite3_vsnprint
1dd30 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61  f() routine is a
1dd40 20 76 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e   varargs version
1dd50 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72   of sqlite3_snpr
1dd60 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68  intf()..**.** Th
1dd70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c  ese routines all
1dd80 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20   implement some 
1dd90 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61  additional forma
1dda0 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73  tting.** options
1ddb0 20 74 68 61 74 20 61 72 65 20 75 73 65 66 75 6c   that are useful
1ddc0 20 66 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e   for constructin
1ddd0 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
1dde0 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20  ..** All of the 
1ddf0 75 73 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66  usual printf() f
1de00 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1de10 73 20 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64  s apply.  In add
1de20 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20  ition, there.** 
1de30 69 73 20 61 72 65 20 22 25 71 22 2c 20 22 25 51  is are "%q", "%Q
1de40 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69  ", and "%z" opti
1de50 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ons..**.** ^(The
1de60 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73   %q option works
1de70 20 6c 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74   like %s in that
1de80 20 69 74 20 73 75 62 73 74 69 74 75 74 65 73 20   it substitutes 
1de90 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64  a nul-terminated
1dea0 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20  .** string from 
1deb0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  the argument lis
1dec0 74 2e 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20  t.  But %q also 
1ded0 64 6f 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c  doubles every '\
1dee0 27 27 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  '' character..**
1def0 20 25 71 20 69 73 20 64 65 73 69 67 6e 65 64 20   %q is designed 
1df00 66 6f 72 20 75 73 65 20 69 6e 73 69 64 65 20 61  for use inside a
1df10 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e   string literal.
1df20 29 5e 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20  )^  By doubling 
1df30 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61  each '\''.** cha
1df40 72 61 63 74 65 72 20 69 74 20 65 73 63 61 70 65  racter it escape
1df50 73 20 74 68 61 74 20 63 68 61 72 61 63 74 65 72  s that character
1df60 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74   and allows it t
1df70 6f 20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e  o be inserted in
1df80 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  to.** the string
1df90 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d  ..**.** For exam
1dfa0 70 6c 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20  ple, assume the 
1dfb0 73 74 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20  string variable 
1dfc0 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74  zText contains t
1dfd0 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ext as follows:.
1dfe0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1dff0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1e000 20 2a 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20   *zText = "It's 
1e010 61 20 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a  a happy day!";.*
1e020 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e030 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20  uote>.**.** One 
1e040 63 61 6e 20 75 73 65 20 74 68 69 73 20 74 65 78  can use this tex
1e050 74 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74  t in an SQL stat
1e060 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73  ement as follows
1e070 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1e080 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68  ote><pre>.**  ch
1e090 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74  ar *zSQL = sqlit
1e0a0 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45  e3_mprintf("INSE
1e0b0 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41  RT INTO table VA
1e0c0 4c 55 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65  LUES('%q')", zTe
1e0d0 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
1e0e0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
1e0f0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
1e100 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
1e110 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1e120 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42  ckquote>.**.** B
1e130 65 63 61 75 73 65 20 74 68 65 20 25 71 20 66 6f  ecause the %q fo
1e140 72 6d 61 74 20 73 74 72 69 6e 67 20 69 73 20 75  rmat string is u
1e150 73 65 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68  sed, the '\'' ch
1e160 61 72 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74  aracter in zText
1e170 0a 2a 2a 20 69 73 20 65 73 63 61 70 65 64 20 61  .** is escaped a
1e180 6e 64 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72  nd the SQL gener
1e190 61 74 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f  ated is as follo
1e1a0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1e1b0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e1c0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e1d0 65 31 20 56 41 4c 55 45 53 28 27 49 74 27 27 73  e1 VALUES('It''s
1e1e0 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29 0a   a happy day!').
1e1f0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1e200 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69  quote>.**.** Thi
1e210 73 20 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48  s is correct.  H
1e220 61 64 20 77 65 20 75 73 65 64 20 25 73 20 69 6e  ad we used %s in
1e230 73 74 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65  stead of %q, the
1e240 20 67 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a   generated SQL.*
1e250 2a 20 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f  * would have loo
1e260 6b 65 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ked like this:.*
1e270 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e280 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1e290 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1e2a0 4c 55 45 53 28 27 49 74 27 73 20 61 20 68 61 70  LUES('It's a hap
1e2b0 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f  py day!');.** </
1e2c0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1e2d0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63  >.**.** This sec
1e2e0 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61  ond example is a
1e2f0 6e 20 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72  n SQL syntax err
1e300 6f 72 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61  or.  As a genera
1e310 6c 20 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c  l rule you shoul
1e320 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20  d.** always use 
1e330 25 71 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73  %q instead of %s
1e340 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20   when inserting 
1e350 74 65 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69  text into a stri
1e360 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a  ng literal..**.*
1e370 2a 20 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f  * ^(The %Q optio
1e380 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20  n works like %q 
1e390 65 78 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61  except it also a
1e3a0 64 64 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65  dds single quote
1e3b0 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20  s around.** the 
1e3c0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20 74  outside of the t
1e3d0 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64  otal string.  Ad
1e3e0 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74  ditionally, if t
1e3f0 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20  he parameter in 
1e400 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  the.** argument 
1e410 6c 69 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70  list is a NULL p
1e420 6f 69 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74  ointer, %Q subst
1e430 69 74 75 74 65 73 20 74 68 65 20 74 65 78 74 20  itutes the text 
1e440 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a  "NULL" (without.
1e450 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73  ** single quotes
1e460 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78  ).)^  So, for ex
1e470 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64  ample, one could
1e480 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f   say:.**.** <blo
1e490 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1e4a0 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1e4b0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1e4c0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e4d0 65 20 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a  e VALUES(%Q)", z
1e4e0 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  Text);.**  sqlit
1e4f0 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c  e3_exec(db, zSQL
1e500 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20  , 0, 0, 0);.**  
1e510 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51  sqlite3_free(zSQ
1e520 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  L);.** </pre></b
1e530 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e540 20 54 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20   The code above 
1e550 77 69 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f  will render a co
1e560 72 72 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d  rrect SQL statem
1e570 65 6e 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a  ent in the zSQL.
1e580 2a 2a 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e  ** variable even
1e590 20 69 66 20 74 68 65 20 7a 54 65 78 74 20 76 61   if the zText va
1e5a0 72 69 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c  riable is a NULL
1e5b0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1e5c0 5e 28 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61  ^(The "%z" forma
1e5d0 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72  tting option wor
1e5e0 6b 73 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74  ks like "%s" but
1e5f0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64   with the.** add
1e600 69 74 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72  ition that after
1e610 20 74 68 65 20 73 74 72 69 6e 67 20 68 61 73 20   the string has 
1e620 62 65 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f  been read and co
1e630 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  pied into.** the
1e640 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65   result, [sqlite
1e650 33 5f 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c  3_free()] is cal
1e660 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74  led on the input
1e670 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51   string.)^.*/.SQ
1e680 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1e690 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1e6a0 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1e6b0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1e6c0 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e   *sqlite3_vmprin
1e6d0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  tf(const char*, 
1e6e0 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45  va_list);.SQLITE
1e6f0 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74  _API char *sqlit
1e700 65 33 5f 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  e3_snprintf(int,
1e710 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1e720 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f  *, ...);.SQLITE_
1e730 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65  API char *sqlite
1e740 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c  3_vsnprintf(int,
1e750 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1e760 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a  *, va_list);../*
1e770 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
1e780 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
1e790 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20  Subsystem.**.** 
1e7a0 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20  The SQLite core 
1e7b0 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65  uses these three
1e7c0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c   routines for al
1e7d0 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20  l of its own.** 
1e7e0 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
1e7f0 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
1e800 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20  . "Core" in the 
1e810 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63  previous sentenc
1e820 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e  e.** does not in
1e830 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d  clude operating-
1e840 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20  system specific 
1e850 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
1e860 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64  on.  The.** Wind
1e870 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74  ows VFS uses nat
1e880 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  ive malloc() and
1e890 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65   free() for some
1e8a0 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
1e8b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1e8c0 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65  malloc() routine
1e8d0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
1e8e0 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a  er to a block.**
1e8f0 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65   of memory at le
1e900 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c  ast N bytes in l
1e910 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69  ength, where N i
1e920 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  s the parameter.
1e930 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1e940 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62  malloc() is unab
1e950 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66  le to obtain suf
1e960 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20  ficient free.** 
1e970 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72  memory, it retur
1e980 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
1e990 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61  r.  ^If the para
1e9a0 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71  meter N to.** sq
1e9b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69  lite3_malloc() i
1e9c0 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69  s zero or negati
1e9d0 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ve then sqlite3_
1e9e0 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  malloc() returns
1e9f0 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  .** a NULL point
1ea00 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  er..**.** ^Calli
1ea10 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ng sqlite3_free(
1ea20 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72  ) with a pointer
1ea30 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75   previously retu
1ea40 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1ea50 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1ea60 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ea70 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d   releases that m
1ea80 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74  emory so.** that
1ea90 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75   it might be reu
1eaa0 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  sed.  ^The sqlit
1eab0 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e  e3_free() routin
1eac0 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20  e is.** a no-op 
1ead0 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  if is called wit
1eae0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
1eaf0 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c  .  Passing a NUL
1eb00 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  L pointer.** to 
1eb10 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1eb20 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74  s harmless.  Aft
1eb30 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20  er being freed, 
1eb40 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64  memory.** should
1eb50 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64   neither be read
1eb60 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45   nor written.  E
1eb70 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76  ven reading prev
1eb80 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20  iously freed.** 
1eb90 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73  memory might res
1eba0 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74  ult in a segment
1ebb0 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f  ation fault or o
1ebc0 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1ebd0 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72  r..** Memory cor
1ebe0 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65  ruption, a segme
1ebf0 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f  ntation fault, o
1ec00 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1ec10 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65  rror.** might re
1ec20 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f  sult if sqlite3_
1ec30 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64  free() is called
1ec40 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
1ec50 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a   pointer that.**
1ec60 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65   was not obtaine
1ec70 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d  d from sqlite3_m
1ec80 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74  alloc() or sqlit
1ec90 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1eca0 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1ecb0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65  3_realloc() inte
1ecc0 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
1ecd0 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72  o resize a.** pr
1ece0 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ior memory alloc
1ecf0 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c  ation to be at l
1ed00 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68  east N bytes, wh
1ed10 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
1ed20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1ed30 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c  .  The memory al
1ed40 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72  location to be r
1ed50 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69  esized is the fi
1ed60 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
1ed70 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72  .)^ ^ If the fir
1ed80 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1ed90 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1eda0 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70  ).** is a NULL p
1edb0 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20  ointer then its 
1edc0 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e  behavior is iden
1edd0 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67  tical to calling
1ede0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  .** sqlite3_mall
1edf0 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73  oc(N) where N is
1ee00 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1ee10 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1ee20 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
1ee30 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  If the second pa
1ee40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1ee50 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20  e3_realloc() is 
1ee60 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74  zero or.** negat
1ee70 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68  ive then the beh
1ee80 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79  avior is exactly
1ee90 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c   the same as cal
1eea0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1eeb0 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20  free(P) where P 
1eec0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
1eed0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1eee0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1eef0 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  ^sqlite3_realloc
1ef00 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  () returns a poi
1ef10 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79  nter to a memory
1ef20 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f   allocation.** o
1ef30 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74  f at least N byt
1ef40 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55  es in size or NU
1ef50 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74  LL if sufficient
1ef60 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61   memory is unava
1ef70 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d  ilable..** ^If M
1ef80 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20   is the size of 
1ef90 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1efa0 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e  tion, then min(N
1efb0 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  ,M) bytes.** of 
1efc0 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
1efd0 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20  tion are copied 
1efe0 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69  into the beginni
1eff0 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74  ng of buffer ret
1f000 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1f010 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e  te3_realloc() an
1f020 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  d the prior allo
1f030 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e  cation is freed.
1f040 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  .** ^If sqlite3_
1f050 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  realloc() return
1f060 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  s NULL, then the
1f070 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1f080 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65  n.** is not free
1f090 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  d..**.** ^The me
1f0a0 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79  mory returned by
1f0b0 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f0c0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
1f0d0 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c  alloc().** is al
1f0e0 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20  ways aligned to 
1f0f0 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79  at least an 8 by
1f100 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20  te boundary, or 
1f110 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62  to a.** 4 byte b
1f120 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b  oundary if the [
1f130 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c  SQLITE_4_BYTE_AL
1f140 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f  IGNED_MALLOC] co
1f150 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70  mpile-time.** op
1f160 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a  tion is used..**
1f170 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65  .** In SQLite ve
1f180 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20  rsion 3.5.0 and 
1f190 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f  3.5.1, it was po
1f1a0 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65  ssible to define
1f1b0 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  .** the SQLITE_O
1f1c0 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43  MIT_MEMORY_ALLOC
1f1d0 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c  ATION which woul
1f1e0 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c  d cause the buil
1f1f0 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  t-in.** implemen
1f200 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20  tation of these 
1f210 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f  routines to be o
1f220 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61  mitted.  That ca
1f230 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e  pability.** is n
1f240 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65  o longer provide
1f250 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69  d.  Only built-i
1f260 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
1f270 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e  ors can be used.
1f280 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20  .**.** Prior to 
1f290 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
1f2a0 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f  .7.10, the Windo
1f2b0 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20  ws OS interface 
1f2c0 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20  layer called.** 
1f2d0 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f  the system mallo
1f2e0 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64  c() and free() d
1f2f0 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e  irectly when con
1f300 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e  verting.** filen
1f310 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65  ames between the
1f320 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20   UTF-8 encoding 
1f330 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a  used by SQLite.*
1f340 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66  * and whatever f
1f350 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67  ilename encoding
1f360 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20   is used by the 
1f370 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f  particular Windo
1f380 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69  ws.** installati
1f390 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f  on.  Memory allo
1f3a0 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65  cation errors we
1f3b0 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74  re detected, but
1f3c0 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65  .** they were re
1f3d0 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b  ported back as [
1f3e0 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d  SQLITE_CANTOPEN]
1f3f0 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49   or.** [SQLITE_I
1f400 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61  OERR] rather tha
1f410 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d  n [SQLITE_NOMEM]
1f420 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ..**.** The poin
1f430 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ter arguments to
1f440 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1f450 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  ] and [sqlite3_r
1f460 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73  ealloc()].** mus
1f470 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c  t be either NULL
1f480 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72   or else pointer
1f490 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  s obtained from 
1f4a0 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63  a prior.** invoc
1f4b0 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1f4c0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b  3_malloc()] or [
1f4d0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f4e0 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20  )] that have.** 
1f4f0 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c  not yet been rel
1f500 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eased..**.** The
1f510 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
1f520 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72  t not read or wr
1f530 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a  ite any part of.
1f540 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65  ** a block of me
1f550 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61  mory after it ha
1f560 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20  s been released 
1f570 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
1f580 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71  3_free()] or [sq
1f590 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1f5a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1f5b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61  void *sqlite3_ma
1f5c0 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54  lloc(int);.SQLIT
1f5d0 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
1f5e0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64  te3_realloc(void
1f5f0 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
1f600 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
1f610 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
1f620 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1f630 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
1f640 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
1f650 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
1f660 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
1f670 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
1f680 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
1f690 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
1f6a0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
1f6b0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1f6c0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
1f6d0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
1f6e0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
1f6f0 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
1f700 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1f710 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
1f720 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1f730 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
1f740 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1f750 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1f760 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
1f770 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
1f780 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
1f790 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
1f7a0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1f7b0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1f7c0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
1f7d0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
1f7e0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
1f7f0 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1f800 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
1f810 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1f820 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
1f830 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
1f840 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1f850 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1f860 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1f870 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1f880 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
1f890 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
1f8a0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
1f8b0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
1f8c0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1f8d0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
1f8e0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
1f8f0 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
1f900 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
1f910 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
1f920 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
1f930 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
1f940 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
1f950 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
1f960 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
1f970 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
1f980 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
1f990 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1f9a0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
1f9b0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
1f9c0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
1f9d0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1f9e0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
1f9f0 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1fa00 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
1fa10 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1fa20 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
1fa30 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1fa40 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
1fa50 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  reset..*/.SQLITE
1fa60 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74  _API sqlite3_int
1fa70 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
1fa80 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 53 51  y_used(void);.SQ
1fa90 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
1faa0 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1fab0 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1fac0 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b 0a  int resetFlag);.
1fad0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1fae0 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e   Pseudo-Random N
1faf0 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72 0a  umber Generator.
1fb00 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e  **.** SQLite con
1fb10 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75 61  tains a high-qua
1fb20 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e 64  lity pseudo-rand
1fb30 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72 61  om number genera
1fb40 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64 20  tor (PRNG) used 
1fb50 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e  to.** select ran
1fb60 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57  dom [ROWID | ROW
1fb70 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72 74  IDs] when insert
1fb80 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73 20  ing new records 
1fb90 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68 61  into a table tha
1fba0 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73 65  t.** already use
1fbb0 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70 6f  s the largest po
1fbc0 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20  ssible [ROWID]. 
1fbd0 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c 73   The PRNG is als
1fbe0 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68  o used for.** th
1fbf0 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f  e build-in rando
1fc00 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c  m() and randombl
1fc10 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  ob() SQL functio
1fc20 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72 66  ns.  This interf
1fc30 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70  ace allows.** ap
1fc40 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
1fc50 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50 52  cess the same PR
1fc60 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75 72  NG for other pur
1fc70 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20  poses..**.** ^A 
1fc80 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f 75  call to this rou
1fc90 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62 79  tine stores N by
1fca0 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73  tes of randomnes
1fcb0 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50 2e  s into buffer P.
1fcc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
1fcd0 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75 74  t time this rout
1fce0 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 28  ine is invoked (
1fcf0 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c  either internall
1fd00 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20 61  y or by.** the a
1fd10 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65 20  pplication) the 
1fd20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20 75  PRNG is seeded u
1fd30 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20  sing randomness 
1fd40 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d  obtained.** from
1fd50 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   the xRandomness
1fd60 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 64   method of the d
1fd70 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f  efault [sqlite3_
1fd80 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  vfs] object..** 
1fd90 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75 65  ^On all subseque
1fda0 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20  nt invocations, 
1fdb0 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f  the pseudo-rando
1fdc0 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61 74  mness is generat
1fdd0 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79  ed.** internally
1fde0 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63   and without rec
1fdf0 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71  ourse to the [sq
1fe00 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64  lite3_vfs] xRand
1fe10 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64  omness.** method
1fe20 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
1fe30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
1fe40 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
1fe50 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
1fe60 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
1fe70 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
1fe80 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
1fe90 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1fea0 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
1feb0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fec0 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
1fed0 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1fee0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
1fef0 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
1ff00 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
1ff10 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
1ff20 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1ff30 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
1ff40 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
1ff50 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
1ff60 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1ff70 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1ff80 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
1ff90 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
1ffa0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1ffb0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
1ffc0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1ffd0 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
1ffe0 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
1fff0 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
20000 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
20010 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
20020 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
20030 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
20040 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
20050 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
20060 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
20070 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
20080 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
20090 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
200a0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
200b0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
200c0 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
200d0 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
200e0 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
200f0 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
20100 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
20110 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
20120 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
20130 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
20140 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
20150 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
20160 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
20170 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
20180 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
20190 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
201a0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
201b0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
201c0 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
201d0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
201e0 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
201f0 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
20200 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
20210 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
20220 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
20230 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
20240 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
20250 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
20260 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
20270 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
20280 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
20290 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
202a0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
202b0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
202c0 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
202d0 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
202e0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
202f0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
20300 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
20310 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20320 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
20330 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
20340 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
20350 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
20360 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
20370 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
20380 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
20390 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
203a0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
203b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
203c0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
203d0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
203e0 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
203f0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
20400 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
20410 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
20420 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
20430 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
20440 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
20450 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
20460 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
20470 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
20480 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
20490 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
204a0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
204b0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
204c0 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
204d0 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
204e0 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
204f0 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
20500 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
20510 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
20520 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
20530 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
20540 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
20550 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
20560 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
20570 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
20580 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
20590 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
205a0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
205b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
205c0 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
205d0 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
205e0 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
205f0 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
20600 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
20610 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
20620 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
20630 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
20640 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
20650 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
20660 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
20670 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
20680 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
20690 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
206a0 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
206b0 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
206c0 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
206d0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
206e0 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
206f0 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
20700 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
20710 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
20720 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
20730 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
20740 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
20750 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
20760 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
20770 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
20780 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
20790 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
207a0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
207b0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
207c0 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
207d0 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
207e0 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
207f0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
20800 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
20810 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
20820 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
20830 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
20840 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
20850 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
20860 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
20870 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
20880 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
20890 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
208a0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
208b0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
208c0 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
208d0 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
208e0 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
208f0 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
20900 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
20910 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
20920 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
20930 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
20940 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
20950 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
20960 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
20970 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
20980 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
20990 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
209a0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
209b0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
209c0 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
209d0 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
209e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
209f0 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
20a00 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
20a10 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
20a20 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
20a30 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
20a40 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
20a50 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
20a60 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
20a70 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
20a80 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
20a90 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
20aa0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
20ab0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
20ac0 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
20ad0 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
20ae0 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
20af0 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
20b00 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
20b10 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
20b20 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
20b30 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
20b40 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
20b50 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
20b60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20b70 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
20b80 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
20b90 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
20ba0 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
20bb0 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
20bc0 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
20bd0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
20be0 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
20bf0 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
20c00 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
20c10 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
20c20 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
20c30 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20c40 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
20c50 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
20c60 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
20c70 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
20c80 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
20c90 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
20ca0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
20cb0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
20cc0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20cd0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
20ce0 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
20cf0 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
20d00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
20d10 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
20d20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
20d30 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
20d40 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
20d50 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
20d60 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
20d70 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
20d80 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
20d90 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
20da0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
20db0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
20dc0 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
20dd0 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
20de0 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
20df0 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
20e00 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
20e10 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
20e20 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
20e30 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
20e40 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
20e50 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
20e60 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
20e70 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20e80 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
20e90 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
20ea0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
20eb0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
20ec0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
20ed0 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
20ee0 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
20ef0 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
20f00 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
20f10 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
20f20 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
20f30 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
20f40 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
20f50 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
20f60 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
20f70 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
20f80 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
20f90 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
20fa0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
20fb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  int sqlite3_set_
20fc0 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71  authorizer(.  sq
20fd0 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a  lite3*,.  int (*
20fe0 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74  xAuth)(void*,int
20ff0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
21000 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
21010 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
21020 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72  ),.  void *pUser
21030 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  Data.);../*.** C
21040 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
21050 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73  zer Return Codes
21060 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
21070 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
21080 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20  er | authorizer 
21090 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
210a0 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72  n] must.** retur
210b0 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45  n either [SQLITE
210c0 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  _OK] or one of t
210d0 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e  hese two constan
210e0 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74  ts in order.** t
210f0 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20  o signal SQLite 
21100 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
21110 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72  he action is per
21120 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65  mitted.  See the
21130 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  .** [sqlite3_set
21140 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75  _authorizer | au
21150 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e  thorizer documen
21160 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69  tation] for addi
21170 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d  tional.** inform
21180 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  ation..**.** Not
21190 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47  e that SQLITE_IG
211a0 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65  NORE is also use
211b0 64 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52  d as a [SQLITE_R
211c0 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e  OLLBACK | return
211d0 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74   code].** from t
211e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  he [sqlite3_vtab
211f0 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
21200 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64  interface..*/.#d
21210 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e  efine SQLITE_DEN
21220 59 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74  Y   1   /* Abort
21230 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
21240 6e 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  nt with an error
21250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21260 54 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a  TE_IGNORE 2   /*
21270 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63   Don't allow acc
21280 65 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67  ess, but don't g
21290 65 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72  enerate an error
212a0 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
212b0 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20  REF: Authorizer 
212c0 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a  Action Codes.**.
212d0 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
212e0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29  set_authorizer()
212f0 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ] interface regi
21300 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
21310 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61   function.** tha
21320 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20  t is invoked to 
21330 61 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69  authorize certai
21340 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
21350 61 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a  actions.  The.**
21360 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
21370 72 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  r to the callbac
21380 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  k is an integer 
21390 63 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66  code that specif
213a0 69 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69  ies.** what acti
213b0 6f 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68  on is being auth
213c0 6f 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61  orized.  These a
213d0 72 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61  re the integer a
213e0 63 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74  ction codes that
213f0 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a  .** the authoriz
21400 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20  er callback may 
21410 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a  be passed..**.**
21420 20 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f   These action co
21430 64 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66  de values signif
21440 79 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f  y what kind of o
21450 70 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62  peration is to b
21460 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e  e.** authorized.
21470 20 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74    The 3rd and 4t
21480 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  h parameters to 
21490 74 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f  the authorizatio
214a0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75  n.** callback fu
214b0 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70  nction will be p
214c0 61 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c  arameters or NUL
214d0 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77  L depending on w
214e0 68 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a  hich of these.**
214f0 20 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61   codes is used a
21500 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
21510 61 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35  ameter.  ^(The 5
21520 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
21530 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65  the.** authorize
21540 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
21550 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
21560 74 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20  tabase ("main", 
21570 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29  "temp",.** etc.)
21580 20 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29   if applicable.)
21590 5e 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61  ^  ^The 6th para
215a0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
215b0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
215c0 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20  .** is the name 
215d0 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73  of the inner-mos
215e0 74 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65  t trigger or vie
215f0 77 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e  w that is respon
21600 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65  sible for.** the
21610 20 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20   access attempt 
21620 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20  or NULL if this 
21630 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69  access attempt i
21640 73 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a  s directly from.
21650 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c  ** top-level SQL
21660 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a   code..*/./*****
21670 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21680 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21690 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a  ****** 3rd *****
216a0 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a  ******* 4th ****
216b0 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65  *******/.#define
216c0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49   SQLITE_CREATE_I
216d0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20  NDEX          1 
216e0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
216f0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
21700 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21710 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41  SQLITE_CREATE_TA
21720 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20  BLE          2  
21730 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21740 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21750 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21760 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
21770 50 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20  P_INDEX     3   
21780 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
21790 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
217a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
217b0 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
217c0 5f 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f  _TABLE     4   /
217d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
217e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
217f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21800 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
21810 54 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a  TRIGGER   5   /*
21820 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
21830 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21840 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21850 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56  TE_CREATE_TEMP_V
21860 49 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20  IEW      6   /* 
21870 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
21880 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21890 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
218a0 45 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52  E_CREATE_TRIGGER
218b0 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54          7   /* T
218c0 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54  rigger Name    T
218d0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
218e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
218f0 5f 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20  _CREATE_VIEW    
21900 20 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69         8   /* Vi
21910 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55  ew Name       NU
21920 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21930 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21940 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
21950 20 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62        9   /* Tab
21960 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21970 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21980 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21990 52 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ROP_INDEX       
219a0 20 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65      10   /* Inde
219b0 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c  x Name      Tabl
219c0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
219d0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
219e0 4f 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  OP_TABLE        
219f0 20 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65     11   /* Table
21a00 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21a10 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21a20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21a30 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  P_TEMP_INDEX    
21a40 20 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20    12   /* Index 
21a50 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
21a60 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21a70 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21a80 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
21a90 20 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   13   /* Table N
21aa0 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
21ab0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21ac0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21ad0 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20  TEMP_TRIGGER    
21ae0 31 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20  14   /* Trigger 
21af0 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61  Name    Table Na
21b00 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
21b10 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21b20 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31  EMP_VIEW       1
21b30 35 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65  5   /* View Name
21b40 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20         NULL     
21b50 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21b60 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52  e SQLITE_DROP_TR
21b70 49 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36  IGGER         16
21b80 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
21b90 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
21ba0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21bb0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45   SQLITE_DROP_VIE
21bc0 57 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20  W            17 
21bd0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
21be0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21bf0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21c00 53 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20  SQLITE_INSERT   
21c10 20 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20              18  
21c20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21c30 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21c40 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21c50 51 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20  QLITE_PRAGMA    
21c60 20 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20             19   
21c70 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20  /* Pragma Name  
21c80 20 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55     1st arg or NU
21c90 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  LL */.#define SQ
21ca0 4c 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20  LITE_READ       
21cb0 20 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f            20   /
21cc0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21cd0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
21ce0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21cf0 49 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20  ITE_SELECT      
21d00 20 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a           21   /*
21d10 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21d20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21d30 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21d40 54 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20  TE_TRANSACTION  
21d50 20 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20          22   /* 
21d60 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
21d70 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
21d80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21d90 45 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20  E_UPDATE        
21da0 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54         23   /* T
21db0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
21dc0 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
21dd0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21de0 5f 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20  _ATTACH         
21df0 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69        24   /* Fi
21e00 6c 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55  lename        NU
21e10 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21e20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21e30 44 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20  DETACH          
21e40 20 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74       25   /* Dat
21e50 61 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c  abase Name   NUL
21e60 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21e70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
21e80 4c 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20  LTER_TABLE      
21e90 20 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61      26   /* Data
21ea0 62 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c  base Name   Tabl
21eb0 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21ec0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
21ed0 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20  INDEX           
21ee0 20 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78     27   /* Index
21ef0 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20   Name      NULL 
21f00 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21f10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41  efine SQLITE_ANA
21f20 4c 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  LYZE            
21f30 20 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20    28   /* Table 
21f40 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21f50 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21f60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21f70 54 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  TE_VTABLE       
21f80 20 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   29   /* Table N
21f90 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20  ame      Module 
21fa0 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
21fb0 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21fc0 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  VTABLE          
21fd0 33 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  30   /* Table Na
21fe0 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
21ff0 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
22000 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49  ne SQLITE_FUNCTI
22010 4f 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33  ON             3
22020 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20  1   /* NULL     
22030 20 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20         Function 
22040 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e  Name   */.#defin
22050 65 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49  e SQLITE_SAVEPOI
22060 4e 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32  NT            32
22070 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20     /* Operation 
22080 20 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20        Savepoint 
22090 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65  Name  */.#define
220a0 20 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20   SQLITE_COPY    
220b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20                0 
220c0 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75    /* No longer u
220d0 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  sed */../*.** CA
220e0 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20  PI3REF: Tracing 
220f0 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75  And Profiling Fu
22100 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  nctions.**.** Th
22110 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67  ese routines reg
22120 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66  ister callback f
22130 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61  unctions that ca
22140 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a  n be used for.**
22150 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f   tracing and pro
22160 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75  filing the execu
22170 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74  tion of SQL stat
22180 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ements..**.** ^T
22190 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
221a0 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20  tion registered 
221b0 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  by sqlite3_trace
221c0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74  () is invoked at
221d0 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65  .** various time
221e0 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74  s when an SQL st
221f0 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67  atement is being
22200 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33   run by [sqlite3
22210 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68  _step()]..** ^Th
22220 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  e sqlite3_trace(
22230 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  ) callback is in
22240 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46  voked with a UTF
22250 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  -8 rendering of 
22260 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  the.** SQL state
22270 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65  ment text as the
22280 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74   statement first
22290 20 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e   begins executin
222a0 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e  g..** ^(Addition
222b0 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65  al sqlite3_trace
222c0 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67  () callbacks mig
222d0 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65  ht occur.** as e
222e0 61 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75  ach triggered su
222f0 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65  bprogram is ente
22300 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61  red.  The callba
22310 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73  cks for triggers
22320 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54  .** contain a UT
22330 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20  F-8 SQL comment 
22340 74 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20  that identifies 
22350 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a  the trigger.)^.*
22360 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
22370 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
22380 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
22390 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
223a0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
223b0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
223c0 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
223d0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
223e0 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
223f0 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
22400 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
22410 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
22420 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
22430 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
22440 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
22450 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
22460 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
22470 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
22480 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
22490 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
224a0 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
224b0 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
224c0 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
224d0 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
224e0 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
224f0 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
22500 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
22510 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
22520 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
22530 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
22540 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
22550 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
22560 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
22570 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
22580 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
22590 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f  rofile() functio
225a0 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  n is considered 
225b0 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
225c0 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74   is.** subject t
225d0 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  o change in futu
225e0 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
225f0 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  QLite..*/.SQLITE
22600 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
22610 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
22620 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
22630 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
22640 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
22650 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 45  ITE_API SQLITE_E
22660 58 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64  XPERIMENTAL void
22670 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c   *sqlite3_profil
22680 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76  e(sqlite3*,.   v
22690 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76  oid(*xProfile)(v
226a0 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  oid*,const char*
226b0 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29  ,sqlite3_uint64)
226c0 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
226d0 20 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79   CAPI3REF: Query
226e0 20 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61   Progress Callba
226f0 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
22700 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f  qlite3_progress_
22710 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29  handler(D,N,X,P)
22720 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
22730 73 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a  s the callback.*
22740 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20  * function X to 
22750 62 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f  be invoked perio
22760 64 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c  dically during l
22770 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c  ong running call
22780 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
22790 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74  _exec()], [sqlit
227a0 65 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b  e3_step()] and [
227b0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
227c0 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61  e()] for.** data
227d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
227e0 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75  D.  An example u
227f0 73 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69  se for this.** i
22800 6e 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b  nterface is to k
22810 65 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65  eep a GUI update
22820 64 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65  d during a large
22830 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54   query..**.** ^T
22840 68 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  he parameter P i
22850 73 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  s passed through
22860 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72   as the only par
22870 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a  ameter to the .*
22880 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
22890 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72  ion X.  ^The par
228a0 61 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20  ameter N is the 
228b0 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76  number of .** [v
228c0 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69  irtual machine i
228d0 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61  nstructions] tha
228e0 74 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  t are evaluated 
228f0 62 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69  between successi
22900 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e  ve.** invocation
22910 73 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63  s of the callbac
22920 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79  k X..**.** ^Only
22930 20 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65   a single progre
22940 73 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62  ss handler may b
22950 65 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65  e defined at one
22960 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61   time per.** [da
22970 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22980 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65  n]; setting a ne
22990 77 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  w progress handl
229a0 65 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a  er cancels the.*
229b0 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74  * old one.  ^Set
229c0 74 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58  ting parameter X
229d0 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65   to NULL disable
229e0 73 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  s the progress h
229f0 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  andler..** ^The 
22a00 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
22a10 20 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65   is also disable
22a20 64 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74  d by setting N t
22a30 6f 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a  o a value less.*
22a40 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20  * than 1..**.** 
22a50 5e 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73  ^If the progress
22a60 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
22a70 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20  s non-zero, the 
22a80 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20  operation is.** 
22a90 69 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68  interrupted.  Th
22aa0 69 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62  is feature can b
22ab0 65 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  e used to implem
22ac0 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c  ent a.** "Cancel
22ad0 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55  " button on a GU
22ae0 49 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f  I progress dialo
22af0 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  g box..**.** The
22b00 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
22b10 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20  r callback must 
22b20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
22b30 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
22b40 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
22b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
22b60 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f   invoked the pro
22b70 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a  gress handler..*
22b80 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c  * Note that [sql
22b90 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
22ba0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
22bb0 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64  step()] both mod
22bc0 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74  ify their.** dat
22bd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22be0 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e  s for the meanin
22bf0 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e  g of "modify" in
22c00 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e   this paragraph.
22c10 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  .**.*/.SQLITE_AP
22c20 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  I void sqlite3_p
22c30 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
22c40 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
22c50 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
22c60 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
22c70 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
22c80 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
22c90 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
22ca0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
22cb0 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
22cc0 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
22cd0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
22ce0 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
22cf0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
22d00 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
22d10 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
22d20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
22d30 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
22d40 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
22d50 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
22d60 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
22d70 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
22d80 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
22d90 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
22da0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
22db0 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
22dc0 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
22dd0 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
22de0 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
22df0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
22e00 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
22e10 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
22e20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
22e30 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
22e40 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
22e50 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
22e60 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
22e70 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
22e80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
22e90 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
22ea0 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
22eb0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
22ec0 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
22ed0 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
22ee0 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
22ef0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
22f00 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
22f10 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
22f20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
22f30 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
22f40 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
22f50 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
22f60 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
22f70 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
22f80 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
22f90 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
22fa0 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
22fb0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
22fc0 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
22fd0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
22fe0 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
22ff0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
23000 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
23010 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
23020 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
23030 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
23040 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
23050 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
23060 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
23070 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
23080 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
23090 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
230a0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
230b0 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
230c0 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
230d0 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
230e0 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
230f0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
23100 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
23110 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
23120 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
23130 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
23140 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
23150 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
23160 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
23170 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
23180 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
23190 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
231a0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
231b0 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
231c0 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
231d0 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
231e0 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
231f0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
23200 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
23210 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
23220 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
23230 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
23240 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
23250 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
23260 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
23270 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
23280 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
23290 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
232a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
232b0 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
232c0 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
232d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
232e0 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
232f0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
23300 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
23310 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
23320 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
23330 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
23340 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
23350 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
23360 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
23370 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
23380 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
23390 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
233a0 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
233b0 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
233c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
233d0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
233e0 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
233f0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
23400 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
23410 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
23420 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
23430 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
23440 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
23450 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
23460 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
23470 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
23480 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
23490 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
234a0 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
234b0 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
234c0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
234d0 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
234e0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
234f0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
23500 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
23510 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
23520 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
23530 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
23540 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
23550 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
23560 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
23570 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
23580 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
23590 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
235a0 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
235b0 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
235c0 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
235d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
235e0 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
235f0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
23600 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
23610 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23620 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
23630 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
23640 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
23650 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
23660 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
23670 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
23680 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
23690 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
236a0 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
236b0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
236c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
236d0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
236e0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
236f0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
23700 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
23710 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
23720 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
23730 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
23740 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
23750 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
23760 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
23770 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
23780 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
23790 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
237a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
237b0 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
237c0 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
237d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
237e0 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
237f0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
23800 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
23810 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
23820 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
23830 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
23840 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
23850 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
23860 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
23870 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
23880 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
23890 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
238a0 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
238b0 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
238c0 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
238d0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
238e0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
238f0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
23900 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
23910 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
23920 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
23930 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
23940 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
23950 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
23960 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
23970 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
23980 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
23990 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
239a0 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
239b0 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
239c0 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
239d0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
239e0 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
239f0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
23a00 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
23a10 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
23a20 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
23a30 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
23a40 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
23a50 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
23a60 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
23a70 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
23a80 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
23a90 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
23aa0 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
23ab0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
23ac0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
23ad0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
23ae0 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
23af0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
23b00 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
23b10 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
23b20 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
23b30 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
23b40 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
23b50 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
23b60 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
23b70 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
23b80 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
23b90 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
23ba0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
23bb0 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
23bc0 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
23bd0 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
23be0 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
23bf0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
23c00 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
23c10 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
23c20 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
23c30 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
23c40 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
23c50 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
23c60 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
23c70 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
23c80 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
23c90 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
23ca0 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
23cb0 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
23cc0 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
23cd0 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
23ce0 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
23cf0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
23d00 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
23d10 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
23d20 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
23d30 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
23d40 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
23d50 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
23d60 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
23d70 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
23d80 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
23d90 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
23da0 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
23db0 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
23dc0 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
23dd0 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
23de0 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
23df0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
23e00 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
23e10 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
23e20 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
23e30 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
23e40 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
23e50 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
23e60 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
23e70 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
23e80 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
23e90 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
23ea0 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
23eb0 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
23ec0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
23ed0 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
23ee0 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
23ef0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
23f00 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
23f10 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
23f20 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
23f30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
23f40 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
23f50 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
23f60 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
23f70 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
23f80 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
23f90 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
23fa0 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
23fb0 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
23fc0 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
23fd0 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
23fe0 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
23ff0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
24000 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
24010 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
24020 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
24030 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
24040 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
24050 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
24060 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
24070 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
24080 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
24090 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
240a0 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
240b0 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
240c0 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
240d0 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
240e0 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
240f0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
24100 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
24110 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
24120 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
24130 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
24140 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
24150 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
24160 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
24170 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
24180 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
24190 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
241a0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
241b0 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
241c0 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
241d0 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
241e0 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
241f0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
24200 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
24210 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
24220 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
24230 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
24240 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
24250 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
24260 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
24270 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
24280 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
24290 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
242a0 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
242b0 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
242c0 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
242d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
242e0 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
242f0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
24300 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e  ath. .** ^On win
24310 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
24320 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
24330 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
24340 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
24350 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
24360 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   "C:")..**.** [[
24370 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
24380 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
24390 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
243a0 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
243b0 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
243c0 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
243d0 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
243e0 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
243f0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
24400 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
24410 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
24420 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72  * SQLite interpr
24430 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ets the followin
24440 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61  g three query pa
24450 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
24460 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
24470 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
24480 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
24490 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
244a0 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
244b0 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
244c0 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
244d0 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
244e0 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
244f0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
24500 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
24510 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
24520 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
24530 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
24540 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
24550 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
24560 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
24570 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
24580 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
24590 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
245a0 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
245b0 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
245c0 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
245d0 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
245e0 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
245f0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
24600 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
24610 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
24620 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
24630 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
24640 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
24650 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
24660 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
24670 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
24680 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
24690 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
246a0 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
246b0 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
246c0 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
246d0 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
246e0 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
246f0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
24700 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
24710 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
24720 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
24730 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
24740 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
24750 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
24760 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
24770 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
24780 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
24790 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
247a0 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
247b0 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
247c0 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
247d0 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72 65 70   to sqlite3_prep
247e0 61 72 65 5f 76 32 28 29 2e 20 5e 49 66 20 74 68  are_v2(). ^If th
247f0 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
24800 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20   set to .**     
24810 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64  "rw", then the d
24820 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
24830 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65  d for read-write
24840 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65   (but not create
24850 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  ) .**     access
24860 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f  , as if SQLITE_O
24870 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62  PEN_READWRITE (b
24880 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50  ut not SQLITE_OP
24890 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a  EN_CREATE) had .
248a0 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e  **     been set.
248b0 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73   ^Value "rwc" is
248c0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
248d0 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20  etting both .** 
248e0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
248f0 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51  READWRITE and SQ
24900 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
24910 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  .  ^If the mode 
24920 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
24930 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22   set to "memory"
24940 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e   then a pure [in
24950 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
24960 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61  ] that never rea
24970 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69  ds.**     or wri
24980 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73  tes from disk is
24990 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e   used. ^It is an
249a0 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
249b0 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a  y a value for.**
249c0 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61       the mode pa
249d0 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20  rameter that is 
249e0 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
249f0 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
24a00 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74  fied by.**     t
24a10 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20  he flags passed 
24a20 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
24a30 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
24a40 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
24a50 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
24a60 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
24a70 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
24a80 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
24a90 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
24aa0 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
24ab0 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
24ac0 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
24ad0 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
24ae0 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
24af0 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
24b00 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
24b10 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
24b20 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
24b30 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
24b40 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
24b50 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
24b60 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
24b70 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
24b80 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
24b90 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
24ba0 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
24bb0 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
24bc0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
24bd0 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
24be0 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
24bf0 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
24c00 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
24c10 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
24c20 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
24c30 69 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62  iour requested b
24c40 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
24c50 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
24c60 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
24c70 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
24c80 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f  ACHE flag..** </
24c90 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
24ca0 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
24cb0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
24cc0 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
24cd0 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
24ce0 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
24cf0 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
24d00 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
24d10 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
24d20 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
24d30 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
24d40 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
24d50 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
24d60 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
24d70 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
24d80 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
24d90 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
24da0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
24db0 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
24dc0 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
24dd0 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
24de0 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
24df0 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
24e00 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
24e10 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
24e20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
24e30 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
24e40 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
24e50 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
24e60 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
24e70 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
24e80 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
24e90 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
24ea0 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
24eb0 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
24ec0 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
24ed0 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
24ee0 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
24ef0 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
24f00 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
24f10 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
24f20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
24f30 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
24f40 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
24f50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
24f60 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
24f70 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
24f80 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
24f90 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
24fa0 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
24fb0 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
24fc0 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
24fd0 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
24fe0 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
24ff0 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
25000 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
25010 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
25020 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
25030 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
25040 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
25050 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
25060 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
25070 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
25080 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
25090 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
250a0 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
250b0 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
250c0 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
250d0 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
250e0 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
250f0 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
25100 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
25110 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
25120 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
25130 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
25140 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
25150 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
25160 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
25170 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
25180 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
25190 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
251a0 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
251b0 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
251c0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
251d0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
251e0 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
251f0 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
25200 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
25210 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
25220 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
25230 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
25240 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f  a.db?vfs=unix-no
25250 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  lock <td>.**    
25260 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
25270 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
25280 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
25290 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
252a0 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e  nolock"..** <tr>
252b0 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
252c0 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
252d0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
252e0 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
252f0 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
25300 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
25310 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
25320 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
25330 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
25340 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
25350 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
25360 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
25370 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
25380 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
25390 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
253a0 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
253b0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
253c0 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
253d0 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
253e0 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
253f0 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
25400 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
25410 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
25420 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
25430 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
25440 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
25450 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
25460 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
25470 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
25480 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
25490 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
254a0 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
254b0 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
254c0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
254d0 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
254e0 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
254f0 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
25500 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
25510 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
25520 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
25530 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
25540 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
25550 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
25560 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
25570 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
25580 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
25590 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
255a0 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
255b0 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
255c0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
255d0 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
255e0 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
255f0 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
25600 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
25610 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
25620 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
25630 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
25640 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
25650 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
25660 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
25670 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
25680 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
25690 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
256a0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
256b0 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
256c0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
256d0 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
256e0 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
256f0 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
25700 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
25710 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
25720 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
25730 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
25740 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
25750 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
25760 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
25770 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
25780 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
25790 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
257a0 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y].*/.SQLITE_API
257b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
257c0 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
257d0 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
257e0 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
257f0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
25800 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
25810 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
25820 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
25830 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
25840 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
25850 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
25860 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
25870 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
25880 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
25890 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
258a0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
258b0 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
258c0 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
258d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
258e0 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
258f0 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
25900 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
25910 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
25920 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
25930 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
25940 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
25950 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
25960 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
25970 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
25980 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
25990 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
259a0 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
259b0 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
259c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
259d0 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
259e0 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
259f0 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
25a00 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
25a10 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
25a20 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
25a30 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
25a40 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
25a50 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
25a60 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
25a70 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
25a80 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
25a90 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
25aa0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
25ab0 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
25ac0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
25ad0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
25ae0 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
25af0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
25b00 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
25b10 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
25b20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
25b30 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
25b40 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
25b50 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
25b60 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
25b70 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
25b80 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
25b90 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
25ba0 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
25bb0 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
25bc0 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
25bd0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
25be0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
25bf0 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
25c00 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
25c10 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
25c20 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
25c30 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
25c40 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
25c50 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
25c60 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
25c70 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
25c80 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
25c90 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
25ca0 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
25cb0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
25cc0 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
25cd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
25ce0 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
25cf0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
25d00 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
25d10 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
25d20 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
25d30 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
25d40 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
25d50 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
25d60 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
25d70 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
25d80 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
25d90 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
25da0 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
25db0 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
25dc0 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
25dd0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
25de0 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
25df0 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
25e00 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
25e10 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
25e20 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
25e30 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
25e40 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
25e50 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
25e60 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
25e70 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
25e80 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
25e90 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
25ea0 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
25eb0 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
25ec0 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
25ed0 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
25ee0 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
25ef0 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
25f00 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
25f10 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
25f20 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
25f30 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
25f40 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
25f50 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
25f60 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
25f70 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
25f80 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
25f90 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
25fa0 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
25fb0 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
25fc0 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
25fd0 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
25fe0 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
25ff0 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
26000 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
26010 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
26020 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
26030 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
26040 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
26050 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
26060 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
26070 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
26080 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
26090 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
260a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
260b0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
260c0 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
260d0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
260e0 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
260f0 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
26100 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
26110 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
26120 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
26130 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
26140 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
26150 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
26160 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
26170 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
26180 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
26190 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
261a0 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
261b0 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
261c0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
261d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
261e0 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
261f0 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
26200 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
26210 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51  har *zParam);.SQ
26220 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
26230 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
26240 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
26250 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
26260 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
26270 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ault);.SQLITE_AP
26280 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
26290 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
262a0 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
262b0 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
262c0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
262d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
262e0 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
262f0 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
26300 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
26310 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
26320 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
26330 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
26340 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
26350 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
26360 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
26370 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
26380 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
26390 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
263a0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
263b0 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
263c0 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
263d0 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
263e0 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
263f0 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
26400 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
26410 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
26420 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
26430 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
26440 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
26450 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
26460 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
26470 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
26480 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
26490 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
264a0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
264b0 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
264c0 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
264d0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
264e0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
264f0 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
26500 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
26510 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
26520 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
26530 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
26540 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
26550 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
26560 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
26570 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
26580 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
26590 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
265a0 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
265b0 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
265c0 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
265d0 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
265e0 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
265f0 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
26600 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
26610 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
26620 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
26630 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
26640 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
26650 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
26660 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
26670 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
26680 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69  When the seriali
26690 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
266a0 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20  ode] is in use, 
266b0 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a  it might be the.
266c0 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73  ** case that a s
266d0 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75  econd error occu
266e0 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65  rs on a separate
266f0 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65   thread in betwe
26700 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f  en.** the time o
26710 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f  f the first erro
26720 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74  r and the call t
26730 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
26740 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74  es..** When that
26750 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65   happens, the se
26760 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20  cond error will 
26770 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63  be reported sinc
26780 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72  e these.** inter
26790 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70  faces always rep
267a0 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ort the most rec
267b0 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20  ent result.  To 
267c0 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65  avoid.** this, e
267d0 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f  ach thread can o
267e0 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20  btain exclusive 
267f0 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
26800 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
26810 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e   D.** by invokin
26820 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
26830 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33  _enter]([sqlite3
26840 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62  _db_mutex](D)) b
26850 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a  efore beginning.
26860 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20  ** to use D and 
26870 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65  invoking [sqlite
26880 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b  3_mutex_leave]([
26890 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78  sqlite3_db_mutex
268a0 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61  ](D)) after.** a
268b0 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ll calls to the 
268c0 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65  interfaces liste
268d0 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c  d here are compl
268e0 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  eted..**.** If a
268f0 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c  n interface fail
26900 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49  s with SQLITE_MI
26910 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73  SUSE, that means
26920 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
26930 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e  * was invoked in
26940 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65  correctly by the
26950 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49   application.  I
26960 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65  n that case, the
26970 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61  .** error code a
26980 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f  nd message may o
26990 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74  r may not be set
269a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
269b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63  int sqlite3_errc
269c0 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29  ode(sqlite3 *db)
269d0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
269e0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
269f0 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  d_errcode(sqlite
26a00 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41  3 *db);.SQLITE_A
26a10 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  PI const char *s
26a20 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
26a30 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f  lite3*);.SQLITE_
26a40 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
26a50 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36  sqlite3_errmsg16
26a60 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
26a70 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
26a80 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
26a90 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  t.** KEYWORDS: {
26aa0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26ab0 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74  nt} {prepared st
26ac0 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20  atements}.**.** 
26ad0 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  An instance of t
26ae0 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65  his object repre
26af0 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53  sents a single S
26b00 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  QL statement..**
26b10 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
26b20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20  variously known 
26b30 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73  as a "prepared s
26b40 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a  tatement" or a.*
26b50 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20  * "compiled SQL 
26b60 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69  statement" or si
26b70 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65  mply as a "state
26b80 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment"..**.** The
26b90 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65   life of a state
26ba0 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73  ment object goes
26bb0 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20   something like 
26bc0 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  this:.**.** <ol>
26bd0 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20  .** <li> Create 
26be0 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
26bf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
26c00 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c  e_v2()] or a rel
26c10 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e  ated.**      fun
26c20 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42  ction..** <li> B
26c30 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68  ind values to [h
26c40 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20  ost parameters] 
26c50 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
26c60 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20  3_bind_*().**   
26c70 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a     interfaces..*
26c80 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53  * <li> Run the S
26c90 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  QL by calling [s
26ca0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
26cb0 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ne or more times
26cc0 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20  ..** <li> Reset 
26cd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73  the statement us
26ce0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ing [sqlite3_res
26cf0 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61  et()] then go ba
26d00 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74  ck.**      to st
26d10 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a  ep 2.  Do this z
26d20 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  ero or more time
26d30 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72  s..** <li> Destr
26d40 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73  oy the object us
26d50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  ing [sqlite3_fin
26d60 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f  alize()]..** </o
26d70 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74  l>.**.** Refer t
26d80 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20  o documentation 
26d90 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65  on individual me
26da0 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20  thods above for 
26db0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
26dc0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79  formation..*/.ty
26dd0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
26de0 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65  ite3_stmt sqlite
26df0 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43  3_stmt;../*.** C
26e00 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d  API3REF: Run-tim
26e10 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e  e Limits.**.** ^
26e20 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20  (This interface 
26e30 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20  allows the size 
26e40 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74  of various const
26e50 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69  ructs to be limi
26e60 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e  ted.** on a conn
26e70 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63  ection by connec
26e80 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65  tion basis.  The
26e90 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
26ea0 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61   is the.** [data
26eb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
26ec0 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20   whose limit is 
26ed0 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65  to be set or que
26ee0 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ried.  The.** se
26ef0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
26f00 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69  s one of the [li
26f10 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20  mit categories] 
26f20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a  that define a.**
26f30 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72   class of constr
26f40 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20  ucts to be size 
26f50 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68  limited.  The th
26f60 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ird parameter is
26f70 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69   the.** new limi
26f80 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74  t for that const
26f90 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49  ruct.)^.**.** ^I
26fa0 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20  f the new limit 
26fb0 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75  is a negative nu
26fc0 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20  mber, the limit 
26fd0 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a  is unchanged..**
26fe0 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69   ^(For each limi
26ff0 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54  t category SQLIT
27000 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c  E_LIMIT_<i>NAME<
27010 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a  /i> there is a .
27020 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72  ** [limits | har
27030 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a  d upper bound].*
27040 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65  * set at compile
27050 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65  -time by a C pre
27060 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
27070 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74  called.** [limit
27080 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c  s | SQLITE_MAX_<
27090 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20  i>NAME</i>]..** 
270a0 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69  (The "_LIMIT_" i
270b0 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68  n the name is ch
270c0 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22  anged to "_MAX_"
270d0 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74  .))^.** ^Attempt
270e0 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20  s to increase a 
270f0 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20  limit above its 
27100 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
27110 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79   are.** silently
27120 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68   truncated to th
27130 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  e hard upper bou
27140 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72  nd..**.** ^Regar
27150 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
27160 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69   or not the limi
27170 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74  t was changed, t
27180 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  he .** [sqlite3_
27190 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61  limit()] interfa
271a0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70  ce returns the p
271b0 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68  rior value of th
271c0 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e  e limit..** ^Hen
271d0 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20  ce, to find the 
271e0 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66  current value of
271f0 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74   a limit without
27200 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a   changing it,.**
27210 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74   simply invoke t
27220 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69  his interface wi
27230 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72  th the third par
27240 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31  ameter set to -1
27250 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65  ..**.** Run-time
27260 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65   limits are inte
27270 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20  nded for use in 
27280 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  applications tha
27290 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68  t manage.** both
272a0 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72   their own inter
272b0 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64  nal database and
272c0 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20   also databases 
272d0 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c  that are control
272e0 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73  led.** by untrus
272f0 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75  ted external sou
27300 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c  rces.  An exampl
27310 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69  e application mi
27320 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20  ght be a.** web 
27330 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73  browser that has
27340 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73   its own databas
27350 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68  es for storing h
27360 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65  istory and.** se
27370 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73  parate databases
27380 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a   controlled by J
27390 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63  avaScript applic
273a0 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65  ations downloade
273b0 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74  d.** off the Int
273c0 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65  ernet.  The inte
273d0 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63  rnal databases c
273e0 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a  an be given the.
273f0 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c  ** large, defaul
27400 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62  t limits.  Datab
27410 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20  ases managed by 
27420 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73  external sources
27430 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e   can.** be given
27440 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69   much smaller li
27450 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f  mits designed to
27460 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61   prevent a denia
27470 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20  l of service.** 
27480 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70  attack.  Develop
27490 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77  ers might also w
274a0 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b  ant to use the [
274b0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
274c0 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74  orizer()].** int
274d0 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65  erface to furthe
274e0 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73  r control untrus
274f0 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69  ted SQL.  The si
27500 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ze of the databa
27510 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79  se.** created by
27520 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63   an untrusted sc
27530 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74  ript can be cont
27540 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a  ained using the.
27550 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  ** [max_page_cou
27560 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a  nt] [PRAGMA]..**
27570 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65  .** New run-time
27580 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65   limit categorie
27590 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
275a0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
275b0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
275c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d   int sqlite3_lim
275d0 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  it(sqlite3*, int
275e0 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29   id, int newVal)
275f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27600 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69  F: Run-Time Limi
27610 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20  t Categories.** 
27620 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74  KEYWORDS: {limit
27630 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d   category} {*lim
27640 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a  it categories}.*
27650 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
27660 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69  ants define vari
27670 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ous performance 
27680 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63  limits.** that c
27690 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74  an be lowered at
276a0 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20   run-time using 
276b0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
276c0 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73  ]..** The synops
276d0 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e  is of the meanin
276e0 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75  gs of the variou
276f0 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77  s limits is show
27700 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69  n below..** Addi
27710 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
27720 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  on is available 
27730 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d  at [limits | Lim
27740 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a  its in SQLite]..
27750 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
27760 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
27770 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  GTH]] ^(<dt>SQLI
27780 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c  TE_LIMIT_LENGTH<
27790 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
277a0 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20  maximum size of 
277b0 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c  any string or BL
277c0 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c  OB or table row,
277d0 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e   in bytes.<dd>)^
277e0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
277f0 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
27800 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
27810 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48  LIMIT_SQL_LENGTH
27820 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27830 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
27840 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  of an SQL statem
27850 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f  ent, in bytes.</
27860 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
27870 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
27880 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  N]] ^(<dt>SQLITE
27890 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64  _LIMIT_COLUMN</d
278a0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
278b0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
278c0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62  columns in a tab
278d0 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72  le definition or
278e0 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c   in the.** resul
278f0 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
27900 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d  CT] or the maxim
27910 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  um number of col
27920 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
27930 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44  .** or in an ORD
27940 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42  ER BY or GROUP B
27950 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e  Y clause.</dd>)^
27960 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27970 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
27980 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
27990 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
279a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
279b0 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f   maximum depth o
279c0 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65  f the parse tree
279d0 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69   on any expressi
279e0 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
279f0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
27a00 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d  COMPOUND_SELECT]
27a10 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27a20 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
27a30 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LECT</dt>.** <dd
27a40 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
27a50 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20  ber of terms in 
27a60 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43  a compound SELEC
27a70 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64  T statement.</dd
27a80 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
27a90 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50  TE_LIMIT_VDBE_OP
27aa0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
27ab0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64  LIMIT_VDBE_OP</d
27ac0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
27ad0 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
27ae0 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20  instructions in 
27af0 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e  a virtual machin
27b00 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65  e program.** use
27b10 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
27b20 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
27b30 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20    This limit is 
27b40 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a  not currently.**
27b50 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67   enforced, thoug
27b60 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  h that might be 
27b70 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75  added in some fu
27b80 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
27b90 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29  ** SQLite.</dd>)
27ba0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
27bb0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
27bc0 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  ARG]] ^(<dt>SQLI
27bd0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
27be0 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  N_ARG</dt>.** <d
27bf0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
27c00 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
27c10 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e  s on a function.
27c20 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
27c30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
27c40 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51  ACHED]] ^(<dt>SQ
27c50 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
27c60 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HED</dt>.** <dd>
27c70 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
27c80 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20  er of [ATTACH | 
27c90 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
27ca0 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  es].)^</dd>.**.*
27cb0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
27cc0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
27cd0 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  NGTH]].** ^(<dt>
27ce0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b  SQLITE_LIMIT_LIK
27cf0 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48  E_PATTERN_LENGTH
27d00 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27d10 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
27d20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61  of the pattern a
27d30 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
27d40 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f  LIKE] or.** [GLO
27d50 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64  B] operators.</d
27d60 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
27d70 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
27d80 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e  LE_NUMBER]].** ^
27d90 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
27da0 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
27db0 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  R</dt>.** <dd>Th
27dc0 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20  e maximum index 
27dd0 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70  number of any [p
27de0 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20  arameter] in an 
27df0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e  SQL statement.)^
27e00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27e10 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45  LIMIT_TRIGGER_DE
27e20 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  PTH]] ^(<dt>SQLI
27e30 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
27e40 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  _DEPTH</dt>.** <
27e50 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  dd>The maximum d
27e60 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f  epth of recursio
27e70 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c  n for triggers.<
27e80 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
27e90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
27ea0 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20  E_LIMIT_LENGTH  
27eb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27ec0 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
27ed0 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e  TE_LIMIT_SQL_LEN
27ee0 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
27ef0 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
27f00 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
27f10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27f20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
27f30 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
27f40 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20  DEPTH           
27f50 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
27f60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
27f70 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20  OUND_SELECT     
27f80 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
27f90 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
27fa0 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20  E_OP            
27fb0 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
27fc0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55   SQLITE_LIMIT_FU
27fd0 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20  NCTION_ARG      
27fe0 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
27ff0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  e SQLITE_LIMIT_A
28000 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20  TTACHED         
28010 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69           7.#defi
28020 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
28030 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
28040 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66  GTH       8.#def
28050 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
28060 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
28070 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65             9.#de
28080 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
28090 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20  T_TRIGGER_DEPTH 
280a0 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f             10../
280b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
280c0 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20  ompiling An SQL 
280d0 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59  Statement.** KEY
280e0 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74  WORDS: {SQL stat
280f0 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a  ement compiler}.
28100 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65  **.** To execute
28110 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69   an SQL query, i
28120 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20  t must first be 
28130 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20  compiled into a 
28140 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f  byte-code.** pro
28150 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f  gram using one o
28160 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
28170 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
28180 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22  t argument, "db"
28190 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65  , is a [database
281a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74   connection] obt
281b0 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  ained from a.** 
281c0 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c  prior successful
281d0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
281e0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
281f0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f  te3_open_v2()] o
28200 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
28210 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61  en16()].  The da
28220 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
28230 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20  n must not have 
28240 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  been closed..**.
28250 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
28260 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20  gument, "zSql", 
28270 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  is the statement
28280 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c   to be compiled,
28290 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65   encoded.** as e
282a0 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
282b0 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69  TF-16.  The sqli
282c0 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e  te3_prepare() an
282d0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
282e0 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66  e_v2().** interf
282f0 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20  aces use UTF-8, 
28300 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
28310 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69  are16() and sqli
28320 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
28330 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36  ().** use UTF-16
28340 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
28350 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69  nByte argument i
28360 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f  s less than zero
28370 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72  , then zSql is r
28380 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a  ead up to the.**
28390 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
283a0 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74  inator. ^If nByt
283b0 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
283c0 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68  e, then it is th
283d0 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d  e maximum.** num
283e0 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65  ber of  bytes re
283f0 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e  ad from zSql.  ^
28400 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f  When nByte is no
28410 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a  n-negative, the.
28420 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65  ** zSql string e
28430 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68  nds at either th
28440 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f  e first '\000' o
28450 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61  r '\u0000' chara
28460 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e  cter or.** the n
28470 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68  Byte-th byte, wh
28480 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69  ichever comes fi
28490 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c  rst. If the call
284a0 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74  er knows.** that
284b0 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74   the supplied st
284c0 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d  ring is nul-term
284d0 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65  inated, then the
284e0 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a  re is a small.**
284f0 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76   performance adv
28500 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69  antage to be gai
28510 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61  ned by passing a
28520 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65  n nByte paramete
28530 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75  r that.** is equ
28540 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72  al to the number
28550 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
28560 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69   input string <i
28570 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a  >including</i>.*
28580 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e  * the nul-termin
28590 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68  ator bytes as th
285a0 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20  is saves SQLite 
285b0 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a  from having to.*
285c0 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66  * make a copy of
285d0 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
285e0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  g..**.** ^If pzT
285f0 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
28600 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
28610 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
28620 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
28630 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
28640 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
28650 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
28660 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
28670 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
28680 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
28690 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
286a0 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
286b0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
286c0 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
286d0 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
286e0 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
286f0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
28700 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
28710 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
28720 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
28730 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
28740 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
28750 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
28760 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
28770 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
28780 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
28790 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
287a0 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
287b0 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
287c0 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
287d0 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
287e0 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
287f0 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
28800 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
28810 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
28820 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
28830 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
28840 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
28850 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
28860 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
28870 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
28880 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
28890 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
288a0 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
288b0 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
288c0 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
288d0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
288e0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
288f0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
28900 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
28910 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
28920 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
28930 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
28940 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
28950 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
28960 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
28970 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
28980 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
28990 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
289a0 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
289b0 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
289c0 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
289d0 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
289e0 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
289f0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
28a00 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
28a10 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
28a20 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
28a30 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
28a40 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
28a50 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
28a60 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
28a70 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
28a80 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
28a90 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
28aa0 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
28ab0 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
28ac0 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
28ad0 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
28ae0 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
28af0 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
28b00 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
28b10 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
28b20 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
28b30 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
28b40 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
28b50 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
28b60 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
28b70 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
28b80 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
28b90 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a  o run it again..
28ba0 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
28bb0 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
28bc0 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
28bd0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
28be0 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
28bf0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
28c00 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
28c10 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
28c20 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
28c30 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
28c40 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
28c50 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
28c60 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
28c70 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
28c80 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
28c90 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
28ca0 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
28cb0 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
28cc0 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
28cd0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
28ce0 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
28cf0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
28d00 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
28d10 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
28d20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
28d30 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
28d40 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
28d50 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
28d60 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
28d70 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
28d80 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
28d90 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
28da0 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
28db0 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
28dc0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
28dd0 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
28de0 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
28df0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
28e00 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
28e10 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
28e20 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
28e30 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
28e40 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
28e50 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
28e60 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
28e70 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
28e80 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
28e90 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
28ea0 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
28eb0 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
28ec0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
28ed0 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
28ee0 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
28ef0 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
28f00 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
28f10 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
28f20 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
28f30 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
28f40 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
28f50 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
28f60 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
28f70 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
28f80 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
28f90 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
28fa0 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
28fb0 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
28fc0 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
28fd0 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
28fe0 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
28ff0 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70  ABLE_STAT3] comp
29000 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
29010 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74  is enabled..** t
29020 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  he .** </li>.** 
29030 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ol>.*/.SQLITE_
29040 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29050 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74  prepare(.  sqlit
29060 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
29070 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
29080 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
29090 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
290a0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
290b0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
290c0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
290d0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
290e0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
290f0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
29100 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
29110 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
29120 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
29130 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
29140 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
29150 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
29160 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
29170 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
29180 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
29190 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
291a0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
291b0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
291c0 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
291d0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
291e0 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
291f0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
29200 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
29210 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
29220 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
29230 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
29240 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
29250 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
29260 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
29270 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
29280 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
29290 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
292a0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
292b0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
292c0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
292d0 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
292e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
292f0 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
29300 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
29310 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
29320 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
29330 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
29340 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
29350 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
29360 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
29370 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
29380 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
29390 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
293a0 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
293b0 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
293c0 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
293d0 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
293e0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
293f0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
29400 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
29410 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
29420 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
29430 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29440 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20  prepare16_v2(.  
29450 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
29460 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
29470 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
29480 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c  const void *zSql
29490 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
294a0 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36  tatement, UTF-16
294b0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
294c0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
294d0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
294e0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
294f0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
29500 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
29510 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
29520 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
29530 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
29540 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
29550 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
29560 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
29570 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a  f zSql */.);../*
29580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
29590 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65  trieving Stateme
295a0 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68  nt SQL.**.** ^Th
295b0 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  is interface can
295c0 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72   be used to retr
295d0 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70  ieve a saved cop
295e0 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61  y of the origina
295f0 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73  l.** SQL text us
29600 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b  ed to create a [
29610 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
29620 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74  nt] if that stat
29630 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d  ement was.** com
29640 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68  piled using eith
29650 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  er [sqlite3_prep
29660 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71  are_v2()] or [sq
29670 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
29680 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  v2()]..*/.SQLITE
29690 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
296a0 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
296b0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
296c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
296d0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
296e0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
296f0 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
29700 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
29710 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
29720 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
29730 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
29740 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
29750 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
29760 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29770 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
29780 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
29790 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
297a0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
297b0 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
297c0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
297d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
297e0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
297f0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
29800 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
29810 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
29820 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
29830 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
29840 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
29850 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
29860 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
29870 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
29880 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
29890 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
298a0 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
298b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
298c0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
298d0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
298e0 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
298f0 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
29900 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
29910 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
29920 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
29930 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
29940 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
29950 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
29960 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
29970 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
29980 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
29990 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
299a0 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
299b0 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
299c0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
299d0 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
299e0 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
299f0 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
29a00 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
29a10 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
29a20 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
29a30 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
29a40 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
29a50 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
29a60 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
29a70 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
29a80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
29a90 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
29aa0 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
29ab0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
29ac0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
29ad0 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
29ae0 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
29af0 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
29b00 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
29b10 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
29b20 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
29b30 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
29b40 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
29b50 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
29b60 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
29b70 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
29b80 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
29b90 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
29ba0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
29bb0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
29bc0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
29bd0 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
29be0 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
29bf0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
29c00 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
29c10 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
29c20 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
29c30 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
29c40 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
29c50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29c60 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
29c70 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
29c80 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
29c90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
29ca0 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
29cb0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
29cc0 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
29cd0 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
29ce0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29cf0 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
29d00 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
29d10 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
29d20 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
29d30 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
29d40 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
29d50 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
29d60 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
29d70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
29d80 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
29d90 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
29da0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
29db0 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
29dc0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
29dd0 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
29de0 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
29df0 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
29e00 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
29e10 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
29e20 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
29e30 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
29e40 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
29e50 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
29e60 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
29e70 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
29e80 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
29e90 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
29ea0 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
29eb0 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
29ec0 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
29ed0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
29ee0 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
29ef0 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
29f00 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
29f10 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
29f20 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
29f30 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
29f40 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
29f50 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
29f60 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
29f70 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
29f80 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
29f90 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
29fa0 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45   open..*/.SQLITE
29fb0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
29fc0 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74  _stmt_busy(sqlit
29fd0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
29fe0 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61  * CAPI3REF: Dyna
29ff0 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61  mically Typed Va
2a000 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  lue Object.** KE
2a010 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74  YWORDS: {protect
2a020 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
2a030 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  } {unprotected s
2a040 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a  qlite3_value}.**
2a050 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20  .** SQLite uses 
2a060 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  the sqlite3_valu
2a070 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72  e object to repr
2a080 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73  esent all values
2a090 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20  .** that can be 
2a0a0 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61  stored in a data
2a0b0 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69  base table. SQLi
2a0c0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
2a0d0 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68  typing.** for th
2a0e0 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72  e values it stor
2a0f0 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f  es.  ^Values sto
2a100 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76  red in sqlite3_v
2a110 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20  alue objects.** 
2a120 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c  can be integers,
2a130 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2a140 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c  values, strings,
2a150 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e   BLOBs, or NULL.
2a160 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65  .**.** An sqlite
2a170 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d  3_value object m
2a180 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72  ay be either "pr
2a190 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70  otected" or "unp
2a1a0 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f  rotected"..** So
2a1b0 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  me interfaces re
2a1c0 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65  quire a protecte
2a1d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2a1e0 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63    Other interfac
2a1f0 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70  es.** will accep
2a200 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65  t either a prote
2a210 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f  cted or an unpro
2a220 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2a230 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69  alue..** Every i
2a240 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63  nterface that ac
2a250 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61  cepts sqlite3_va
2a260 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70  lue arguments sp
2a270 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68  ecifies.** wheth
2a280 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71  er or not it req
2a290 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65  uires a protecte
2a2a0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e  d sqlite3_value.
2a2b0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73  .**.** The terms
2a2c0 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64   "protected" and
2a2d0 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72   "unprotected" r
2a2e0 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20  efer to whether 
2a2f0 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65  or not.** a mute
2a300 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69  x is held.  An i
2a310 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73  nternal mutex is
2a320 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74   held for a prot
2a330 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2a340 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75  _value object bu
2a350 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65  t no mutex is he
2a360 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ld for an unprot
2a370 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ected.** sqlite3
2a380 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20  _value object.  
2a390 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
2a3a0 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67  piled to be sing
2a3b0 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28  le-threaded.** (
2a3c0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52  with [SQLITE_THR
2a3d0 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77  EADSAFE=0] and w
2a3e0 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72  ith [sqlite3_thr
2a3f0 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72  eadsafe()] retur
2a400 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66  ning 0).** or if
2a410 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69   SQLite is run i
2a420 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64  n one of reduced
2a430 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a   mutex modes .**
2a440 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2a450 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72  SINGLETHREAD] or
2a460 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
2a470 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20  MULTITHREAD].** 
2a480 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f  then there is no
2a490 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74   distinction bet
2a4a0 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61  ween protected a
2a4b0 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  nd unprotected.*
2a4c0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
2a4d0 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79  objects and they
2a4e0 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74   can be used int
2a4f0 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48  erchangeably.  H
2a500 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d  owever,.** for m
2a510 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74  aximum code port
2a520 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65  ability it is re
2a530 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61  commended that a
2a540 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
2a550 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69  till make the di
2a560 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65  stinction betwee
2a570 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20  n protected and 
2a580 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
2a590 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2a5a0 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e  ects even when n
2a5b0 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75  ot strictly requ
2a5c0 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ired..**.** ^The
2a5d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2a5e0 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20  bjects that are 
2a5f0 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65  passed as parame
2a600 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  ters into the.**
2a610 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2a620 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  of [application-
2a630 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
2a640 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65  tions] are prote
2a650 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  cted..** ^The sq
2a660 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2a670 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
2a680 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2a690 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e  n_value()] is un
2a6a0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e  protected..** Un
2a6b0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a6c0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
2a6d0 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  may only be used
2a6e0 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65   with.** [sqlite
2a6f0 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2a700 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  ] and [sqlite3_b
2a710 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ind_value()]..**
2a720 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   The [sqlite3_va
2a730 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  lue_blob | sqlit
2a740 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d  e3_value_type()]
2a750 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e   family of.** in
2a760 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65  terfaces require
2a770 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
2a780 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
2a790 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
2a7a0 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f  uct Mem sqlite3_
2a7b0 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  value;../*.** CA
2a7c0 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63  PI3REF: SQL Func
2a7d0 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a  tion Context Obj
2a7e0 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  ect.**.** The co
2a7f0 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61  ntext in which a
2a800 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65  n SQL function e
2a810 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65  xecutes is store
2a820 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  d in an.** sqlit
2a830 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
2a840 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74  t.  ^A pointer t
2a850 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e  o an sqlite3_con
2a860 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69  text object.** i
2a870 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70  s always first p
2a880 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70  arameter to [app
2a890 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2a8a0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e   SQL functions].
2a8b0 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
2a8c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
2a8d0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2a8e0 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73  ntation will pas
2a8f0 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65  s this.** pointe
2a900 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63  r through into c
2a910 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2a920 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71  _result_int | sq
2a930 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c  lite3_result()],
2a940 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67  .** [sqlite3_agg
2a950 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29  regate_context()
2a960 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72  ], [sqlite3_user
2a970 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _data()],.** [sq
2a980 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2a990 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c  _handle()], [sql
2a9a0 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
2a9b0 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b  ()],.** and/or [
2a9c0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2a9d0 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64  ata()]..*/.typed
2a9e0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
2a9f0 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65  3_context sqlite
2aa00 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a  3_context;../*.*
2aa10 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64  * CAPI3REF: Bind
2aa20 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72  ing Values To Pr
2aa30 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2aa40 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
2aa50 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20  host parameter} 
2aa60 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  {host parameters
2aa70 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
2aa80 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f  r name}.** KEYWO
2aa90 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65  RDS: {SQL parame
2aaa0 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65  ter} {SQL parame
2aab0 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72  ters} {parameter
2aac0 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20   binding}.**.** 
2aad0 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61  ^(In the SQL sta
2aae0 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75  tement text inpu
2aaf0 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72  t to [sqlite3_pr
2ab00 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
2ab10 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a  its variants,.**
2ab20 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65   literals may be
2ab30 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b   replaced by a [
2ab40 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20  parameter] that 
2ab50 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66  matches one of f
2ab60 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70  ollowing.** temp
2ab70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  lates:.**.** <ul
2ab80 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20  >.** <li>  ?.** 
2ab90 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c  <li>  ?NNN.** <l
2aba0 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  :VVV.** <li>
2abb0 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20    @VVV.** <li>  
2abc0 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  $VVV.** </ul>.**
2abd0 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c  .** In the templ
2abe0 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20  ates above, NNN 
2abf0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e  represents an in
2ac00 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a  teger literal,.*
2ac10 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73  * and VVV repres
2ac20 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d  ents an alphanum
2ac30 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e  eric identifier.
2ac40 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  )^  ^The values 
2ac50 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61  of these.** para
2ac60 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c  meters (also cal
2ac70 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65  led "host parame
2ac80 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53  ter names" or "S
2ac90 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a  QL parameters").
2aca0 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73  ** can be set us
2acb0 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
2acc0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2acd0 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a  s defined here..
2ace0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2acf0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
2ad00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2ad10 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c  ) routines is al
2ad20 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  ways.** a pointe
2ad30 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  r to the [sqlite
2ad40 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72  3_stmt] object r
2ad50 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  eturned from.** 
2ad60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2ad70 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61  _v2()] or its va
2ad80 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  riants..**.** ^T
2ad90 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2ada0 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2adb0 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d  of the SQL param
2adc0 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a  eter to be set..
2add0 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74  ** ^The leftmost
2ade0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68   SQL parameter h
2adf0 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31  as an index of 1
2ae00 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d  .  ^When the sam
2ae10 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70  e named.** SQL p
2ae20 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64  arameter is used
2ae30 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c   more than once,
2ae40 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2ae50 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72  equent.** occurr
2ae60 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73  ences have the s
2ae70 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65  ame index as the
2ae80 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63   first occurrenc
2ae90 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78  e..** ^The index
2aea0 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d   for named param
2aeb0 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f  eters can be loo
2aec0 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65  ked up using the
2aed0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2aee0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2aef0 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69  x()] API if desi
2af00 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78  red.  ^The index
2af10 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70  .** for "?NNN" p
2af20 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65  arameters is the
2af30 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a   value of NNN..*
2af40 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65  * ^The NNN value
2af50 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
2af60 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69   1 and the [sqli
2af70 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20  te3_limit()].** 
2af80 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54  parameter [SQLIT
2af90 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
2afa0 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c  _NUMBER] (defaul
2afb0 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a  t value: 999)..*
2afc0 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
2afd0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
2afe0 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f  value to bind to
2aff0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
2b000 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65  **.** ^(In those
2b010 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68   routines that h
2b020 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67  ave a fourth arg
2b030 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65  ument, its value
2b040 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
2b050 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2b060 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f  e parameter.  To
2b070 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76   be clear: the v
2b080 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e  alue is the.** n
2b090 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65  umber of <u>byte
2b0a0 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c  s</u> in the val
2b0b0 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ue, not the numb
2b0c0 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2b0d0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .)^.** ^If the f
2b0e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2b0f0 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
2b100 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65  text() or sqlite
2b110 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a  3_bind_text16().
2b120 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  ** is negative, 
2b130 74 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20  then the length 
2b140 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73  of the string is
2b150 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2b160 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68  f bytes up to th
2b170 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  e first zero ter
2b180 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74  minator..** If t
2b190 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2b1a0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
2b1b0 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65  ind_blob() is ne
2b1c0 67 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20  gative, then.** 
2b1d0 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20  the behavior is 
2b1e0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66  undefined..** If
2b1f0 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20   a non-negative 
2b200 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2b210 20 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20   is provided to 
2b220 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2b230 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  t().** or sqlite
2b240 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
2b250 74 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65  then that parame
2b260 74 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20  ter must be the 
2b270 62 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77  byte offset.** w
2b280 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
2b290 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63  minator would oc
2b2a0 63 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65  cur assuming the
2b2b0 20 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c   string were NUL
2b2c0 0a 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20  .** terminated. 
2b2d0 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72   If any NUL char
2b2e0 61 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20  acters occur at 
2b2f0 62 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73  byte offsets les
2b300 73 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76  s than .** the v
2b310 61 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72  alue of the four
2b320 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65  th parameter the
2b330 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
2b340 73 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c  string value wil
2b350 6c 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62  l.** contain emb
2b360 65 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65  edded NULs.  The
2b370 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65   result of expre
2b380 73 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67  ssions involving
2b390 20 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68   strings.** with
2b3a0 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69   embedded NULs i
2b3b0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
2b3c0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
2b3d0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2b3e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73  3_bind_blob(), s
2b3f0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2b400 28 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  (), and.** sqlit
2b410 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2b420 20 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72   is a destructor
2b430 20 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65   used to dispose
2b440 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a   of the BLOB or.
2b450 2a 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20  ** string after 
2b460 53 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73  SQLite has finis
2b470 68 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54  hed with it.  ^T
2b480 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
2b490 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69   called.** to di
2b4a0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2b4b0 42 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e  B or string even
2b4c0 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20   if the call to 
2b4d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2b4e0 62 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  b(),.** sqlite3_
2b4f0 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20  bind_text(), or 
2b500 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2b510 74 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a  t16() fails.  .*
2b520 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20  * ^If the fifth 
2b530 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74  argument is.** t
2b540 68 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65  he special value
2b550 20 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d   [SQLITE_STATIC]
2b560 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73  , then SQLite as
2b570 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a  sumes that the.*
2b580 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
2b590 20 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61   in static, unma
2b5a0 6e 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20  naged space and 
2b5b0 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
2b5c0 20 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   be freed..** ^I
2b5d0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
2b5e0 6d 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c  ment has the val
2b5f0 75 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53  ue [SQLITE_TRANS
2b600 49 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53  IENT], then.** S
2b610 51 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20  QLite makes its 
2b620 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
2b630 20 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d   of the data imm
2b640 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
2b650 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
2b660 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
2b670 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
2b680 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2b690 64 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75  d_zeroblob() rou
2b6a0 74 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f  tine binds a BLO
2b6b0 42 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68  B of length N th
2b6c0 61 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20  at.** is filled 
2b6d0 77 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41  with zeroes.  ^A
2b6e0 20 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61   zeroblob uses a
2b6f0 20 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66   fixed amount of
2b700 20 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74   memory.** (just
2b710 20 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68   an integer to h
2b720 6f 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68  old its size) wh
2b730 69 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20  ile it is being 
2b740 70 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65  processed..** Ze
2b750 72 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65  roblobs are inte
2b760 6e 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73  nded to serve as
2b770 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
2b780 72 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a  r BLOBs whose.**
2b790 20 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65   content is late
2b7a0 72 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a  r written using.
2b7b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62  ** [sqlite3_blob
2b7c0 5f 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e  _open | incremen
2b7d0 74 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f  tal BLOB I/O] ro
2b7e0 75 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65  utines..** ^A ne
2b7f0 67 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72  gative value for
2b800 20 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65   the zeroblob re
2b810 73 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d  sults in a zero-
2b820 6c 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a  length BLOB..**.
2b830 2a 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68  ** ^If any of th
2b840 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2b850 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
2b860 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
2b870 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f  LL pointer.** fo
2b880 72 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  r the [prepared 
2b890 73 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69  statement] or wi
2b8a0 74 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74  th a prepared st
2b8b0 61 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63  atement for whic
2b8c0 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  h.** [sqlite3_st
2b8d0 65 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63  ep()] has been c
2b8e0 61 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e  alled more recen
2b8f0 74 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65  tly than [sqlite
2b900 33 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74  3_reset()],.** t
2b910 68 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c  hen the call wil
2b920 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
2b930 5f 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e  _MISUSE].  If an
2b940 79 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28  y sqlite3_bind_(
2b950 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20  ).** routine is 
2b960 70 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72  passed a [prepar
2b970 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2b980 61 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  at has been fina
2b990 6c 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65  lized, the.** re
2b9a0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2b9b0 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68  d and probably h
2b9c0 61 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42  armful..**.** ^B
2b9d0 69 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20  indings are not 
2b9e0 63 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b  cleared by the [
2b9f0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2ba00 20 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e   routine..** ^Un
2ba10 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73  bound parameters
2ba20 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
2ba30 20 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   as NULL..**.** 
2ba40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e  ^The sqlite3_bin
2ba50 64 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74  d_* routines ret
2ba60 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  urn [SQLITE_OK] 
2ba70 6f 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e  on success or an
2ba80 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  .** [error code]
2ba90 20 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65   if anything goe
2baa0 73 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51  s wrong..** ^[SQ
2bab0 4c 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72  LITE_RANGE] is r
2bac0 65 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70  eturned if the p
2bad0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65  arameter.** inde
2bae0 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  x is out of rang
2baf0 65 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d  e.  ^[SQLITE_NOM
2bb00 45 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20  EM] is returned 
2bb10 69 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  if malloc() fail
2bb20 73 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  s..**.** See als
2bb30 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2bb40 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2bb50 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2bb60 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2bb70 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  name()], and [sq
2bb80 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2bb90 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2bba0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2bbb0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2bbc0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2bbd0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
2bbe0 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
2bbf0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2bc00 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2bc10 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
2bc20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2bc30 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49  t, double);.SQLI
2bc40 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2bc50 65 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69  e3_bind_int(sqli
2bc60 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
2bc70 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2bc80 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2bc90 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
2bca0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
2bcb0 74 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49  te3_int64);.SQLI
2bcc0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2bcd0 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c  e3_bind_null(sql
2bce0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29  ite3_stmt*, int)
2bcf0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2bd00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2bd10 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
2bd20 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61  , int, const cha
2bd30 72 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  r*, int n, void(
2bd40 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
2bd50 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2bd60 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
2bd70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2bd80 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
2bd90 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
2bda0 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  d*));.SQLITE_API
2bdb0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e   int sqlite3_bin
2bdc0 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f  d_value(sqlite3_
2bdd0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2bde0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t sqlite3_value*
2bdf0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2be00 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  t sqlite3_bind_z
2be10 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  eroblob(sqlite3_
2be20 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20  stmt*, int, int 
2be30 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  n);../*.** CAPI3
2be40 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53  REF: Number Of S
2be50 51 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  QL Parameters.**
2be60 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
2be70 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2be80 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72   find the number
2be90 20 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74   of [SQL paramet
2bea0 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72  ers].** in a [pr
2beb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bec0 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65  ].  SQL paramete
2bed0 72 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66  rs are tokens of
2bee0 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22   the.** form "?"
2bef0 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22  , "?NNN", ":AAA"
2bf00 2c 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41  , "$AAA", or "@A
2bf10 41 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61  AA" that serve a
2bf20 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72  s.** placeholder
2bf30 73 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61  s for values tha
2bf40 74 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62  t are [sqlite3_b
2bf50 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64  ind_blob | bound
2bf60 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61  ].** to the para
2bf70 6d 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65  meters at a late
2bf80 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  r time..**.** ^(
2bf90 54 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74  This routine act
2bfa0 75 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68  ually returns th
2bfb0 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c  e index of the l
2bfc0 61 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73  argest (rightmos
2bfd0 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  t).** parameter.
2bfe0 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65   For all forms e
2bff0 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73  xcept ?NNN, this
2c000 20 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64   will correspond
2c010 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   to the.** numbe
2c020 72 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61  r of unique para
2c030 6d 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61  meters.  If para
2c040 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e  meters of the ?N
2c050 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64  NN form are used
2c060 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62  ,.** there may b
2c070 65 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69  e gaps in the li
2c080 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  st.)^.**.** See 
2c090 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
2c0a0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
2c0b0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
2c0c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2c0d0 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2c0e0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2c0f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2c100 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ex()]..*/.SQLITE
2c110 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2c120 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2c130 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2c140 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
2c150 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41  I3REF: Name Of A
2c160 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a   Host Parameter.
2c170 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2c180 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2c190 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65  r_name(P,N) inte
2c1a0 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a  rface returns.**
2c1b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2c1c0 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d   N-th [SQL param
2c1d0 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72  eter] in the [pr
2c1e0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c1f0 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61  ] P..** ^(SQL pa
2c200 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20  rameters of the 
2c210 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  form "?NNN" or "
2c220 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
2c230 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76  or "$AAA".** hav
2c240 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69  e a name which i
2c250 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e  s the string "?N
2c260 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
2c270 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
2c280 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c  ".** respectivel
2c290 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  y..** In other w
2c2a0 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61  ords, the initia
2c2b0 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20  l ":" or "$" or 
2c2c0 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73  "@" or "?".** is
2c2d0 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72   included as par
2c2e0 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e  t of the name.)^
2c2f0 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20  .** ^Parameters 
2c300 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20  of the form "?" 
2c310 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77  without a follow
2c320 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65  ing integer have
2c330 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20   no name.** and 
2c340 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20  are referred to 
2c350 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72  as "nameless" or
2c360 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61   "anonymous para
2c370 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e  meters"..**.** ^
2c380 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70  The first host p
2c390 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20  arameter has an 
2c3a0 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20  index of 1, not 
2c3b0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  0..**.** ^If the
2c3c0 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20   value N is out 
2c3d0 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74  of range or if t
2c3e0 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65  he N-th paramete
2c3f0 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73  r is.** nameless
2c400 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72  , then NULL is r
2c410 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72  eturned.  ^The r
2c420 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2c430 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55  s.** always in U
2c440 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76  TF-8 encoding ev
2c450 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20  en if the named 
2c460 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a  parameter was.**
2c470 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63   originally spec
2c480 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20  ified as UTF-16 
2c490 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  in [sqlite3_prep
2c4a0 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b  are16()] or.** [
2c4b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2c4c0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2c4d0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2c4e0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2c4f0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2c500 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2c510 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2c520 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2c530 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2c540 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51  _index()]..*/.SQ
2c550 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2c560 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e  har *sqlite3_bin
2c570 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2c580 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2c590 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2c5a0 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20  I3REF: Index Of 
2c5b0 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68  A Parameter With
2c5c0 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a   A Given Name.**
2c5d0 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20  .** ^Return the 
2c5e0 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20  index of an SQL 
2c5f0 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20  parameter given 
2c600 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a  its name.  ^The.
2c610 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72  ** index value r
2c620 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61  eturned is suita
2c630 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74  ble for use as t
2c640 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72  he second.** par
2c650 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74  ameter to [sqlit
2c660 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2c670 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e  ite3_bind()].  ^
2c680 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74  A zero.** is ret
2c690 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63  urned if no matc
2c6a0 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69  hing parameter i
2c6b0 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70  s found.  ^The p
2c6c0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65  arameter.** name
2c6d0 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69   must be given i
2c6e0 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20  n UTF-8 even if 
2c6f0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
2c700 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72  tement.** was pr
2c710 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d  epared from UTF-
2c720 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73  16 text using [s
2c730 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c740 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2c750 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2c760 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2c770 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2c780 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2c790 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2c7a0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2c7b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2c7c0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2c7d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2c7e0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2c7f0 65 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33  er_index(sqlite3
2c800 5f 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68  _stmt*, const ch
2c810 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a  ar *zName);../*.
2c820 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
2c830 65 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20  et All Bindings 
2c840 4f 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74  On A Prepared St
2c850 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43  atement.**.** ^C
2c860 6f 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69  ontrary to the i
2c870 6e 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79  ntuition of many
2c880 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  , [sqlite3_reset
2c890 28 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73  ()] does not res
2c8a0 65 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  et.** the [sqlit
2c8b0 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62  e3_bind_blob | b
2c8c0 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70  indings] on a [p
2c8d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c8e0 74 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73  t]..** ^Use this
2c8f0 20 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65   routine to rese
2c900 74 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d  t all host param
2c910 65 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a  eters to NULL..*
2c920 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2c930 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
2c940 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2c950 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2c960 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2c970 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
2c980 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2c990 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
2c9a0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2c9b0 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2c9c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2c9d0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2c9e0 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
2c9f0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2ca00 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
2ca10 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2ca20 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
2ca30 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
2ca40 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
2ca50 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
2ca60 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2ca70 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
2ca80 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ca90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2caa0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2cab0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2cac0 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
2cad0 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
2cae0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
2caf0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2cb00 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
2cb10 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
2cb20 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
2cb30 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
2cb40 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2cb50 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
2cb60 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2cb70 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
2cb80 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2cb90 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2cba0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2cbb0 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
2cbc0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2cbd0 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
2cbe0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2cbf0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
2cc00 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
2cc10 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
2cc20 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2cc30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2cc40 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
2cc50 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
2cc60 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
2cc70 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2cc80 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
2cc90 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
2cca0 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2ccb0 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
2ccc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
2ccd0 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
2cce0 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
2ccf0 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
2cd00 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cd10 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
2cd20 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
2cd30 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2cd40 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2cd50 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2cd60 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2cd70 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2cd80 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2cd90 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2cda0 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2cdb0 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
2cdc0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2cdd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2cde0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2cdf0 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
2ce00 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
2ce10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
2ce20 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
2ce30 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
2ce40 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
2ce50 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
2ce60 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
2ce70 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
2ce80 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
2ce90 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
2cea0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2ceb0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2cec0 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
2ced0 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
2cee0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
2cef0 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
2cf00 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
2cf10 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
2cf20 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
2cf30 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
2cf40 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
2cf50 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
2cf60 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
2cf70 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
2cf80 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
2cf90 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
2cfa0 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51   the next..*/.SQ
2cfb0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2cfc0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2cfd0 75 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  umn_name(sqlite3
2cfe0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2cff0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d000 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2d010 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  olumn_name16(sql
2d020 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2d030 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
2d040 52 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44  REF: Source Of D
2d050 61 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52  ata In A Query R
2d060 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  esult.**.** ^The
2d070 73 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76  se routines prov
2d080 69 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64  ide a means to d
2d090 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74  etermine the dat
2d0a0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2d0b0 64 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d  d.** table colum
2d0c0 6e 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72  n that is the or
2d0d0 69 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63  igin of a partic
2d0e0 75 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75  ular result colu
2d0f0 6d 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54  mn in.** [SELECT
2d100 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  ] statement..** 
2d110 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  ^The name of the
2d120 20 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62   database or tab
2d130 6c 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e  le or column can
2d140 20 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a   be returned as.
2d150 2a 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d  ** either a UTF-
2d160 38 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  8 or UTF-16 stri
2d170 6e 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62  ng.  ^The _datab
2d180 61 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  ase_ routines re
2d190 74 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61  turn.** the data
2d1a0 62 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f  base name, the _
2d1b0 74 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20  table_ routines 
2d1c0 72 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65  return the table
2d1d0 20 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68   name, and.** th
2d1e0 65 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e  e origin_ routin
2d1f0 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f  es return the co
2d200 6c 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54  lumn name..** ^T
2d210 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2d220 6e 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  ng is valid unti
2d230 6c 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  l the [prepared 
2d240 73 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65  statement] is de
2d250 73 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67  stroyed.** using
2d260 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2d270 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2d280 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2d290 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2d2a0 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2d2b0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2d2c0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2d2d0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2d2e0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2d2f0 69 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  il the same info
2d300 72 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65  rmation is reque
2d310 73 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e  sted.** again in
2d320 20 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63   a different enc
2d330 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  oding..**.** ^Th
2d340 65 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64  e names returned
2d350 20 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61   are the origina
2d360 6c 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d  l un-aliased nam
2d370 65 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74  es of the.** dat
2d380 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e  abase, table, an
2d390 64 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20  d column..**.** 
2d3a0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
2d3b0 65 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74  ent to these int
2d3c0 65 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72  erfaces is a [pr
2d3d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d3e0 5d 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  ]..** ^These fun
2d3f0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e  ctions return in
2d400 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
2d410 74 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63  the Nth result c
2d420 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2d430 79 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  y.** the stateme
2d440 6e 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  nt, where N is t
2d450 68 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69  he second functi
2d460 6f 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  on argument..** 
2d470 5e 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63  ^The left-most c
2d480 6f 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20  olumn is column 
2d490 30 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74  0 for these rout
2d4a0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ines..**.** ^If 
2d4b0 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72  the Nth column r
2d4c0 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73  eturned by the s
2d4d0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65  tatement is an e
2d4e0 78 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20  xpression or.** 
2d4f0 73 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20  subquery and is 
2d500 6e 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c  not a column val
2d510 75 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20  ue, then all of 
2d520 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2d530 72 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20  return.** NULL. 
2d540 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20   ^These routine 
2d550 6d 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72  might also retur
2d560 6e 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f  n NULL if a memo
2d570 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72  ry allocation er
2d580 72 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20  ror.** occurs.  
2d590 5e 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79  ^Otherwise, they
2d5a0 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2d5b0 20 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64   of the attached
2d5c0 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65   database, table
2d5d0 2c 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74  ,.** or column t
2d5e0 68 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74  hat query result
2d5f0 20 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72   column was extr
2d600 61 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a  acted from..**.*
2d610 2a 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f  * ^As with all o
2d620 74 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73  ther SQLite APIs
2d630 2c 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61  , those whose na
2d640 6d 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36  mes end with "16
2d650 22 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d  " return.** UTF-
2d660 31 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e  16 encoded strin
2d670 67 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72  gs and the other
2d680 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2d690 6e 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e  n UTF-8..**.** ^
2d6a0 54 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f  These APIs are o
2d6b0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
2d6c0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
2d6d0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
2d6e0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
2d6f0 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
2d700 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
2d710 73 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a  ssor symbol..**.
2d720 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2d730 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2d740 6e 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68  ne or more of th
2d750 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61  ese routines aga
2d760 69 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a  inst the same.**
2d770 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2d780 65 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61  ent and column a
2d790 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2d7a0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2d7b0 20 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65   are.** undefine
2d7c0 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20  d..**.** If two 
2d7d0 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20  or more threads 
2d7e0 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  call one or more
2d7f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2d800 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2d810 65 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64  e | column metad
2d820 61 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a  ata interfaces].
2d830 2a 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  ** for the same 
2d840 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2d850 65 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20  ent] and result 
2d860 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65  column.** at the
2d870 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2d880 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
2d890 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51  undefined..*/.SQ
2d8a0 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
2d8b0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2d8c0 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
2d8d0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2d8e0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
2d8f0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
2d900 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61  ite3_column_data
2d910 62 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69  base_name16(sqli
2d920 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2d930 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d940 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2d950 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2d960 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2d970 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2d980 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2d990 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2d9a0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2d9b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2d9c0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
2d9d0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2d9e0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71  n_origin_name(sq
2d9f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2da00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2da10 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2da20 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
2da30 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2da40 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  mt*,int);../*.**
2da50 20 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61   CAPI3REF: Decla
2da60 72 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20  red Datatype Of 
2da70 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a  A Query Result.*
2da80 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74  *.** ^(The first
2da90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
2daa0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2dab0 65 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73  ent]..** If this
2dac0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2dad0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2dae0 6e 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63  nt and the Nth c
2daf0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20  olumn of the.** 
2db00 72 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20  returned result 
2db10 73 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c  set of that [SEL
2db20 45 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20  ECT] is a table 
2db30 63 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a  column (not an.*
2db40 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20  * expression or 
2db50 73 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74  subquery) then t
2db60 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2db70 20 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a   of the table.**
2db80 20 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72   column is retur
2db90 6e 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20  ned.)^  ^If the 
2dba0 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2dbb0 65 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20  e result set is 
2dbc0 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e  an.** expression
2dbd0 20 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68   or subquery, th
2dbe0 65 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  en a NULL pointe
2dbf0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2dc00 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2dc10 73 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73  string is always
2dc20 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a   UTF-8 encoded..
2dc30 2a 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d  **.** ^(For exam
2dc40 70 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64  ple, given the d
2dc50 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a  atabase schema:.
2dc60 2a 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42  **.** CREATE TAB
2dc70 4c 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54  LE t1(c1 VARIANT
2dc80 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65  );.**.** and the
2dc90 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65   following state
2dca0 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69  ment to be compi
2dcb0 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43  led:.**.** SELEC
2dcc0 54 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f  T c1 + 1, c1 FRO
2dcd0 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73  M t1;.**.** this
2dce0 20 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72   routine would r
2dcf0 65 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67  eturn the string
2dd00 20 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74   "VARIANT" for t
2dd10 68 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74  he second result
2dd20 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31  .** column (i==1
2dd30 29 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f  ), and a NULL po
2dd40 69 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69  inter for the fi
2dd50 72 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  rst result colum
2dd60 6e 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a  n (i==0).)^.**.*
2dd70 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64  * ^SQLite uses d
2dd80 79 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20  ynamic run-time 
2dd90 74 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73  typing.  ^So jus
2dda0 74 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75  t because a colu
2ddb0 6d 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65  mn.** is declare
2ddc0 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70  d to contain a p
2ddd0 61 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64  articular type d
2dde0 6f 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61  oes not mean tha
2ddf0 74 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74  t the.** data st
2de00 6f 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c  ored in that col
2de10 75 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65  umn is of the de
2de20 63 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51  clared type.  SQ
2de30 4c 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e  Lite is.** stron
2de40 67 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74  gly typed, but t
2de50 68 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e  he typing is dyn
2de60 61 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e  amic not static.
2de70 20 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73    ^Type.** is as
2de80 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e  sociated with in
2de90 64 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c  dividual values,
2dea0 20 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f   not with the co
2deb0 6e 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64  ntainers.** used
2dec0 20 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76   to hold those v
2ded0 61 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45  alues..*/.SQLITE
2dee0 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
2def0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2df00 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
2df10 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2df20 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2df30 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2df40 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71  mn_decltype16(sq
2df50 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2df60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2df70 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53  F: Evaluate An S
2df80 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  QL Statement.**.
2df90 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70  ** After a [prep
2dfa0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2dfb0 68 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65  has been prepare
2dfc0 64 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a  d using either.*
2dfd0 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2dfe0 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
2dff0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2e000 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74  2()] or one of t
2e010 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  he legacy.** int
2e020 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33  erfaces [sqlite3
2e030 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b  _prepare()] or [
2e040 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2e050 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74  6()], this funct
2e060 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63  ion.** must be c
2e070 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72  alled one or mor
2e080 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75  e times to evalu
2e090 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e  ate the statemen
2e0a0 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74  t..**.** The det
2e0b0 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61  ails of the beha
2e0c0 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69  vior of the sqli
2e0d0 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72  te3_step() inter
2e0e0 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f  face depend.** o
2e0f0 6e 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74  n whether the st
2e100 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70  atement was prep
2e110 61 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e  ared using the n
2e120 65 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66  ewer "v2" interf
2e130 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ace.** [sqlite3_
2e140 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
2e150 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  d [sqlite3_prepa
2e160 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68  re16_v2()] or th
2e170 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a  e older legacy.*
2e180 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c  * interface [sql
2e190 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2e1a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2e1b0 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20  pare16()].  The 
2e1c0 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65  use of the.** ne
2e1d0 77 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  w "v2" interface
2e1e0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
2e1f0 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74  for new applicat
2e200 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67  ions but the leg
2e210 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2e220 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74   will continue t
2e230 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a  o be supported..
2e240 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65  **.** ^In the le
2e250 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20  gacy interface, 
2e260 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2e270 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20   will be either 
2e280 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a  [SQLITE_BUSY],.*
2e290 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c  * [SQLITE_DONE],
2e2a0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b   [SQLITE_ROW], [
2e2b0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f  SQLITE_ERROR], o
2e2c0 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  r [SQLITE_MISUSE
2e2d0 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20  ]..** ^With the 
2e2e0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20  "v2" interface, 
2e2f0 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72  any of the other
2e300 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20   [result codes] 
2e310 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
2e320 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69  result codes] mi
2e330 67 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20  ght be returned 
2e340 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  as well..**.** ^
2e350 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65  [SQLITE_BUSY] me
2e360 61 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74  ans that the dat
2e370 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73  abase engine was
2e380 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69   unable to acqui
2e390 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  re the.** databa
2e3a0 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64  se locks it need
2e3b0 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e  s to do its job.
2e3c0 20 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d    ^If the statem
2e3d0 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54  ent is a [COMMIT
2e3e0 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f  ].** or occurs o
2e3f0 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70  utside of an exp
2e400 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
2e410 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20  n, then you can 
2e420 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61  retry the.** sta
2e430 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20  tement.  If the 
2e440 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74  statement is not
2e450 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20   a [COMMIT] and 
2e460 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e  occurs within an
2e470 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61  .** explicit tra
2e480 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f  nsaction then yo
2e490 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63  u should rollbac
2e4a0 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  k the transactio
2e4b0 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74  n before.** cont
2e4c0 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  inuing..**.** ^[
2e4d0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61  SQLITE_DONE] mea
2e4e0 6e 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74  ns that the stat
2e4f0 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68  ement has finish
2e500 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20  ed executing.** 
2e510 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73  successfully.  s
2e520 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2e530 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2e540 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73  ed again on this
2e550 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68   virtual.** mach
2e560 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73  ine without firs
2e570 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
2e580 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72  e3_reset()] to r
2e590 65 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c  eset the virtual
2e5a0 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b  .** machine back
2e5b0 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20   to its initial 
2e5c0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  state..**.** ^If
2e5d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
2e5e0 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65  nt being execute
2e5f0 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61  d returns any da
2e600 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45  ta, then [SQLITE
2e610 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75  _ROW].** is retu
2e620 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61  rned each time a
2e630 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61   new row of data
2e640 20 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72   is ready for pr
2e650 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a  ocessing by the.
2e660 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76  ** caller. The v
2e670 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63  alues may be acc
2e680 65 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20  essed using the 
2e690 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
2e6a0 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71  unctions]..** sq
2e6b0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20  lite3_step() is 
2e6c0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20  called again to 
2e6d0 72 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78  retrieve the nex
2e6e0 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a  t row of data..*
2e6f0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52  *.** ^[SQLITE_ER
2e700 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  ROR] means that 
2e710 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72  a run-time error
2e720 20 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73   (such as a cons
2e730 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74  traint.** violat
2e740 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65  ion) has occurre
2e750 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  d.  sqlite3_step
2e760 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2e770 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2e780 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65  .** the VM. More
2e790 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79   information may
2e7a0 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c   be found by cal
2e7b0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72  ling [sqlite3_er
2e7c0 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74  rmsg()]..** ^Wit
2e7d0 68 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  h the legacy int
2e7e0 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73  erface, a more s
2e7f0 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f  pecific error co
2e800 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c  de (for example,
2e810 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45  .** [SQLITE_INTE
2e820 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  RRUPT], [SQLITE_
2e830 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45  SCHEMA], [SQLITE
2e840 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73  _CORRUPT], and s
2e850 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20  o forth).** can 
2e860 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63  be obtained by c
2e870 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2e880 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a  reset()] on the.
2e890 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2e8a0 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68  tement].  ^In th
2e8b0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2e8c0 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70  ,.** the more sp
2e8d0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2e8e0 65 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69  e is returned di
2e8f0 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65  rectly by sqlite
2e900 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20  3_step()..**.** 
2e910 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2e920 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74  means that the t
2e930 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20  his routine was 
2e940 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72  called inappropr
2e950 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61  iately..** Perha
2e960 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64  ps it was called
2e970 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2e980 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
2e990 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62  has.** already b
2e9a0 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  een [sqlite3_fin
2e9b0 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65  alize | finalize
2e9c0 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61  d] or on one tha
2e9d0 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75  t had.** previou
2e9e0 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51  sly returned [SQ
2e9f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b  LITE_ERROR] or [
2ea00 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f  SQLITE_DONE].  O
2ea10 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65  r it could.** be
2ea20 20 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74   the case that t
2ea30 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
2ea40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62   connection is b
2ea50 65 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f  eing used by two
2ea60 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65   or.** more thre
2ea70 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20  ads at the same 
2ea80 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a  moment in time..
2ea90 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65  **.** For all ve
2eaa0 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
2eab0 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75   up to and inclu
2eac0 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61  ding 3.6.23.1, a
2ead0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2eae0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61  ite3_reset()] wa
2eaf0 73 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72  s required after
2eb00 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2eb10 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e  returned anythin
2eb20 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20  g.** other than 
2eb30 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66  [SQLITE_ROW] bef
2eb40 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65  ore any subseque
2eb50 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  nt invocation of
2eb60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70  .** sqlite3_step
2eb70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20  ().  Failure to 
2eb80 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
2eb90 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  ed statement usi
2eba0 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ng .** [sqlite3_
2ebb0 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72  reset()] would r
2ebc0 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c  esult in an [SQL
2ebd0 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75  ITE_MISUSE] retu
2ebe0 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  rn from.** sqlit
2ebf0 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20  e3_step().  But 
2ec00 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e  after version 3.
2ec10 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f  6.23.1, sqlite3_
2ec20 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20  step() began.** 
2ec30 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
2ec40 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61  _reset()] automa
2ec50 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20  tically in this 
2ec60 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74  circumstance rat
2ec70 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75  her.** than retu
2ec80 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49  rning [SQLITE_MI
2ec90 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20  SUSE].  This is 
2eca0 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61  not considered a
2ecb0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a   compatibility.*
2ecc0 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20  * break because 
2ecd0 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  any application 
2ece0 74 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76  that ever receiv
2ecf0 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53  es an SQLITE_MIS
2ed00 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20  USE error.** is 
2ed10 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69  broken by defini
2ed20 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49  tion.  The [SQLI
2ed30 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45  TE_OMIT_AUTORESE
2ed40 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  T] compile-time 
2ed50 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65  option.** can be
2ed60 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65   used to restore
2ed70 20 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61   the legacy beha
2ed80 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47  vior..**.** <b>G
2ed90 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41  oofy Interface A
2eda0 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65  lert:</b> In the
2edb0 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2edc0 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  e, the sqlite3_s
2edd0 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77  tep().** API alw
2ede0 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65  ays returns a ge
2edf0 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65  neric error code
2ee00 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
2ee10 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a  , following any.
2ee20 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74  ** error other t
2ee30 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  han [SQLITE_BUSY
2ee40 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49  ] and [SQLITE_MI
2ee50 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74  SUSE].  You must
2ee60 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
2ee70 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2ee80 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2ee90 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  )] in order to f
2eea0 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  ind one of the.*
2eeb0 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  * specific [erro
2eec0 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65  r codes] that be
2eed0 74 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74  tter describes t
2eee0 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20  he error..** We 
2eef0 61 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20  admit that this 
2ef00 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67  is a goofy desig
2ef10 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20  n.  The problem 
2ef20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a  has been fixed.*
2ef30 2a 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20  * with the "v2" 
2ef40 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79  interface.  If y
2ef50 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f  ou prepare all o
2ef60 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65  f your SQL state
2ef70 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65  ments.** using e
2ef80 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70  ither [sqlite3_p
2ef90 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2efa0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2efb0 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64  16_v2()] instead
2efc0 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63  .** of the legac
2efd0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
2efe0 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  re()] and [sqlit
2eff0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2f000 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74  interfaces,.** t
2f010 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65  hen the more spe
2f020 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2f030 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64  es] are returned
2f040 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20   directly.** by 
2f050 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2f060 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   The use of the 
2f070 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69  "v2" interface i
2f080 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a  s recommended..*
2f090 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2f0a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71   sqlite3_step(sq
2f0b0 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
2f0c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
2f0d0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2f0e0 20 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74   in a result set
2f0f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f100 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2f110 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
2f120 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2f130 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2f140 0a 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20  .** current row 
2f150 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2f160 74 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  t of [prepared s
2f170 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
2f180 5e 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61  ^If prepared sta
2f190 74 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f  tement P does no
2f1a0 74 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72  t have results r
2f1b0 65 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a  eady to return.*
2f1c0 2a 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20  * (via calls to 
2f1d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  the [sqlite3_col
2f1e0 75 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65  umn_int | sqlite
2f1f0 33 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66  3_column_*()] of
2f200 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20  .** interfaces) 
2f210 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74  then sqlite3_dat
2f220 61 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72  a_count(P) retur
2f230 6e 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ns 0..** ^The sq
2f240 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2f250 28 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f  (P) routine also
2f260 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20   returns 0 if P 
2f270 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2f280 72 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  r..** ^The sqlit
2f290 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2f2a0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2f2b0 20 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f   0 if the previo
2f2c0 75 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  us call to.** [s
2f2d0 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20  qlite3_step](P) 
2f2e0 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2f2f0 5f 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71  _DONE].  ^The sq
2f300 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2f310 28 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75  (P).** will retu
2f320 72 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70  rn non-zero if p
2f330 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
2f340 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50  [sqlite3_step](P
2f350 29 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53  ) returned.** [S
2f360 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65  QLITE_ROW], exce
2f370 70 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f  pt in the case o
2f380 66 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e  f the [PRAGMA in
2f390 63 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d  cremental_vacuum
2f3a0 5d 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c  ].** where it al
2f3b0 77 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72  ways returns zer
2f3c0 6f 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65  o since each ste
2f3d0 70 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d  p of that multi-
2f3e0 73 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72  step.** pragma r
2f3f0 65 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73  eturns 0 columns
2f400 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2f410 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2f420 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2f430 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
2f440 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74   int sqlite3_dat
2f450 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  a_count(sqlite3_
2f460 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2f470 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
2f480 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74  undamental Datat
2f490 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ypes.** KEYWORDS
2f4a0 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a  : SQLITE_TEXT.**
2f4b0 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75  .** ^(Every valu
2f4c0 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20  e in SQLite has 
2f4d0 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64  one of five fund
2f4e0 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65  amental datatype
2f4f0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
2f500 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67   <li> 64-bit sig
2f510 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c  ned integer.** <
2f520 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20  li> 64-bit IEEE 
2f530 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e  floating point n
2f540 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74  umber.** <li> st
2f550 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f  ring.** <li> BLO
2f560 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a  B.** <li> NULL.*
2f570 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
2f580 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
2f590 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61  are codes for ea
2f5a0 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65  ch of those type
2f5b0 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
2f5c0 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45  at the SQLITE_TE
2f5d0 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20  XT constant was 
2f5e0 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c  also used in SQL
2f5f0 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a  ite version 2.**
2f600 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c   for a completel
2f610 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e  y different mean
2f620 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ing.  Software t
2f630 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73  hat links agains
2f640 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65  t both.** SQLite
2f650 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53   version 2 and S
2f660 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20  QLite version 3 
2f670 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54  should use SQLIT
2f680 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20  E3_TEXT, not.** 
2f690 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a  SQLITE_TEXT..*/.
2f6a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
2f6b0 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e  NTEGER  1.#defin
2f6c0 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20  e SQLITE_FLOAT  
2f6d0 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
2f6e0 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64  TE_BLOB     4.#d
2f6f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c  efine SQLITE_NUL
2f700 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53  L     5.#ifdef S
2f710 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64  QLITE_TEXT.# und
2f720 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23  ef SQLITE_TEXT.#
2f730 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51  else.# define SQ
2f740 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a  LITE_TEXT     3.
2f750 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53  #endif.#define S
2f760 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20  QLITE3_TEXT     
2f770 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  3../*.** CAPI3RE
2f780 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73  F: Result Values
2f790 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a   From A Query.**
2f7a0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75   KEYWORDS: {colu
2f7b0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2f7c0 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ons}.**.** These
2f7d0 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74   routines form t
2f7e0 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20  he "result set" 
2f7f0 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
2f800 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2f810 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2f820 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67  ion about a sing
2f830 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  le column of the
2f840 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75   current.** resu
2f850 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72  lt row of a quer
2f860 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61  y.  ^In every ca
2f870 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67  se the first arg
2f880 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74  ument is a point
2f890 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72  er.** to the [pr
2f8a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2f8b0 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20  ] that is being 
2f8c0 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b  evaluated (the [
2f8d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a  sqlite3_stmt*].*
2f8e0 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72  * that was retur
2f8f0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
2f900 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2f910 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61  or one of its va
2f920 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74  riants).** and t
2f930 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
2f940 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20  nt is the index 
2f950 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f  of the column fo
2f960 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74  r which informat
2f970 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65  ion.** should be
2f980 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20   returned. ^The 
2f990 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  leftmost column 
2f9a0 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2f9b0 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20  t has the index 
2f9c0 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65  0..** ^The numbe
2f9d0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2f9e0 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62  the result can b
2f9f0 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69  e determined usi
2fa00 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ng.** [sqlite3_c
2fa10 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a  olumn_count()]..
2fa20 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c  **.** If the SQL
2fa30 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
2fa40 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f  not currently po
2fa50 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72  int to a valid r
2fa60 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a  ow, or if the.**
2fa70 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73   column index is
2fa80 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74   out of range, t
2fa90 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  he result is und
2faa0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65  efined..** These
2fab0 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e   routines may on
2fac0 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
2fad0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
2fae0 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  t call to.** [sq
2faf0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61  lite3_step()] ha
2fb00 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49  s returned [SQLI
2fb10 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74  TE_ROW] and neit
2fb20 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2fb30 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71  reset()] nor [sq
2fb40 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2fb50 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c  ] have been call
2fb60 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e  ed subsequently.
2fb70 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68  .** If any of th
2fb80 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2fb90 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73   called after [s
2fba0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2fbb0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  or.** [sqlite3_f
2fbc0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66  inalize()] or af
2fbd0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ter [sqlite3_ste
2fbe0 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2fbf0 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f  d.** something o
2fc00 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
2fc10 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75  E_ROW], the resu
2fc20 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65  lts are undefine
2fc30 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65  d..** If [sqlite
2fc40 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71  3_step()] or [sq
2fc50 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2fc60 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2fc70 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61  ize()].** are ca
2fc80 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66  lled from a diff
2fc90 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69  erent thread whi
2fca0 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  le any of these 
2fcb0 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20  routines.** are 
2fcc0 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68  pending, then th
2fcd0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
2fce0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2fcf0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
2fd00 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e  mn_type() routin
2fd10 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a  e returns the.**
2fd20 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2fd30 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65   | datatype code
2fd40 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61  ] for the initia
2fd50 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f  l data type.** o
2fd60 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c  f the result col
2fd70 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72  umn.  ^The retur
2fd80 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65  ned value is one
2fd90 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45   of [SQLITE_INTE
2fda0 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  GER],.** [SQLITE
2fdb0 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45  _FLOAT], [SQLITE
2fdc0 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  _TEXT], [SQLITE_
2fdd0 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54  BLOB], or [SQLIT
2fde0 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61  E_NULL].  The va
2fdf0 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
2fe00 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2fe10 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79  n_type() is only
2fe20 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e   meaningful if n
2fe30 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72  o type.** conver
2fe40 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72  sions have occur
2fe50 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64  red as described
2fe60 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61   below.  After a
2fe70 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   type conversion
2fe80 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72  ,.** the value r
2fe90 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2fea0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2feb0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
2fec0 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f  Future.** versio
2fed0 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79  ns of SQLite may
2fee0 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61   change the beha
2fef0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
2ff00 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a  column_type().**
2ff10 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70   following a typ
2ff20 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  e conversion..**
2ff30 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2ff40 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2ff50 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65  UTF-8 string the
2ff60 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2ff70 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20  lumn_bytes().** 
2ff80 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2ff90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2ffa0 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42  tes in that BLOB
2ffb0 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e   or string..** ^
2ffc0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2ffd0 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2ffe0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2fff0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f  olumn_bytes() co
30000 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74  nverts.** the st
30010 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e  ring to UTF-8 an
30020 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
30030 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
30040 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
30050 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
30060 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
30070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30080 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  es() uses.** [sq
30090 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
300a0 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
300b0 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
300c0 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65  -8 string and re
300d0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  turns.** the num
300e0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
300f0 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  that string..** 
30100 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
30110 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c  s NULL, then sql
30120 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30130 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  s() returns zero
30140 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
30150 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42  result is a BLOB
30160 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
30170 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
30180 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
30190 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  6().** routine r
301a0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
301b0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
301c0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
301d0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
301e0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20  sult is a UTF-8 
301f0 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
30200 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30210 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a  s16() converts.*
30220 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20  * the string to 
30230 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20  UTF-16 and then 
30240 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
30250 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20  er of bytes..** 
30260 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
30270 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75  s a numeric valu
30280 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  e then sqlite3_c
30290 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
302a0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
302b0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
302c0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
302d0 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73  ue to a UTF-16 s
302e0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
302f0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
30300 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
30310 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
30320 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
30330 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
30340 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
30350 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
30360 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65  **.** ^The value
30370 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
30380 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30390 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b  tes()] and .** [
303a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
303b0 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74  ytes16()] do not
303c0 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72   include the zer
303d0 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74  o terminators at
303e0 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74   the end.** of t
303f0 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72  he string.  ^For
30400 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61   clarity: the va
30410 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79  lues returned by
30420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
30430 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
30440 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
30450 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20  _bytes16()] are 
30460 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
30470 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74   bytes in the st
30480 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75  ring, not the nu
30490 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
304a0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e  rs..**.** ^Strin
304b0 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  gs returned by s
304c0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
304d0 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  xt() and sqlite3
304e0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
304f0 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20  ,.** even empty 
30500 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77  strings, are alw
30510 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
30520 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ted.  ^The retur
30530 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20  n.** value from 
30540 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30550 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f  lob() for a zero
30560 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20  -length BLOB is 
30570 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a  a NULL pointer..
30580 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63  **.** ^The objec
30590 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  t returned by [s
305a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
305b0 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20  lue()] is an.** 
305c0 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
305d0 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
305e0 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63  ct.  An unprotec
305f0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
30600 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20  e object.** may 
30610 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74  only be used wit
30620 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  h [sqlite3_bind_
30630 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71  value()] and [sq
30640 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
30650 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65  ue()]..** If the
30660 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
30670 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30680 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
30690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
306a0 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
306b0 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72  sed in any other
306c0 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20   way, including 
306d0 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74  calls.** to rout
306e0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
306f0 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c  e3_value_int()],
30700 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30710 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b  text()],.** or [
30720 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
30730 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  tes()], then the
30740 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
30750 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  efined..**.** Th
30760 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74  ese routines att
30770 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20  empt to convert 
30780 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20  the value where 
30790 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46  appropriate.  ^F
307a0 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69  or.** example, i
307b0 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72  f the internal r
307c0 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73  epresentation is
307d0 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78   FLOAT and a tex
307e0 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72  t result.** is r
307f0 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74  equested, [sqlit
30800 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69  e3_snprintf()] i
30810 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c  s used internall
30820 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65  y to perform the
30830 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61  .** conversion a
30840 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e  utomatically.  ^
30850 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  (The following t
30860 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65  able details the
30870 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20   conversions.** 
30880 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64  that are applied
30890 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
308a0 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  ote>.** <table b
308b0 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74  order="1">.** <t
308c0 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c  r><th> Internal<
308d0 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71  br>Type <th> Req
308e0 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c  uested<br>Type <
308f0 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a  th>  Conversion.
30900 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  **.** <tr><td>  
30910 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54  NULL    <td> INT
30920 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75  EGER   <td> Resu
30930 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c  lt is 0.** <tr><
30940 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
30950 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
30960 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a   Result is 0.0.*
30970 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
30980 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
30990 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
309a0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
309b0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
309c0 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
309d0 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
309e0 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  s NULL pointer.*
309f0 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
30a00 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
30a10 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
30a20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
30a30 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
30a40 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
30a50 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
30a60 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
30a70 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
30a80 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
30a90 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
30aa0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
30ab0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
30ac0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
30ad0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
30ae0 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72   <td> Convert fr
30af0 6f 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65  om float to inte
30b00 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
30b10 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20   FLOAT   <td>   
30b20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43  TEXT    <td> ASC
30b30 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20  II rendering of 
30b40 74 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72  the float.** <tr
30b50 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
30b60 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
30b70 64 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54  d> Same as FLOAT
30b80 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74  ->TEXT.** <tr><t
30b90 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  d>  TEXT    <td>
30ba0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
30bb0 55 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  Use atoi().** <t
30bc0 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
30bd0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
30be0 74 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a  td> Use atof().*
30bf0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54  * <tr><td>  TEXT
30c00 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
30c10 20 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67     <td> No chang
30c20 65 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  e.** <tr><td>  B
30c30 4c 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOB    <td> INTE
30c40 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
30c50 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
30c60 75 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74  use atoi().** <t
30c70 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
30c80 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c  <td>  FLOAT    <
30c90 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54  td> Convert to T
30ca0 45 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f  EXT then use ato
30cb0 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
30cc0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
30cd0 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
30ce0 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
30cf0 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
30d00 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
30d10 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
30d20 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
30d30 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
30d40 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
30d50 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
30d60 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
30d70 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
30d80 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
30d90 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
30da0 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
30db0 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
30dc0 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
30dd0 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
30de0 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
30df0 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
30e00 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
30e10 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
30e20 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
30e30 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
30e40 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
30e50 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
30e60 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
30e70 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
30e80 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
30e90 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
30ea0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
30eb0 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
30ec0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
30ed0 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
30ee0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
30ef0 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
30f00 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
30f10 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
30f20 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
30f30 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
30f40 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
30f50 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
30f60 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
30f70 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
30f80 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
30f90 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
30fa0 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
30fb0 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
30fc0 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
30fd0 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
30fe0 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
30ff0 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
31000 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
31010 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
31020 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
31030 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
31040 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
31050 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
31060 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
31070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
31080 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
31090 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
310a0 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
310b0 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
310c0 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
310d0 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
310e0 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
310f0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
31100 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
31110 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
31120 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
31130 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
31140 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
31150 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
31160 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
31170 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
31180 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
31190 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
311a0 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
311b0 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
311c0 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
311d0 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
311e0 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
311f0 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
31200 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
31210 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
31220 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
31230 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
31240 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
31250 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
31260 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
31270 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
31280 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
31290 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
312a0 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
312b0 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
312c0 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
312d0 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
312e0 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
312f0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
31300 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
31310 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
31320 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
31330 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
31340 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
31350 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
31360 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
31370 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
31380 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
31390 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
313a0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
313b0 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
313c0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
313d0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
313e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
313f0 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
31400 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
31410 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
31420 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
31430 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
31440 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
31450 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
31460 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
31470 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
31480 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
31490 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
314a0 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
314b0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
314c0 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
314d0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
314e0 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
314f0 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
31500 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31510 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
31520 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31530 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
31540 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
31550 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
31560 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
31570 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
31580 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
31590 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
315a0 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
315b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
315c0 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
315d0 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
315e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
315f0 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
31600 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
31610 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
31620 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
31630 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
31640 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
31650 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
31660 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
31670 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
31680 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
31690 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
316a0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
316b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
316c0 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
316d0 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
316e0 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
316f0 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
31700 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
31710 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
31720 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
31730 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
31740 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71   returned.** [sq
31750 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
31760 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
31770 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
31780 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
31790 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
317a0 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
317b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
317c0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
317d0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
317e0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
317f0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
31800 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
31810 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
31820 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
31830 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
31840 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
31850 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
31860 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
31870 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
31880 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
31890 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
318a0 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
318b0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
318c0 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54  MEM].)^.*/.SQLIT
318d0 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
318e0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
318f0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74  _blob(sqlite3_st
31900 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
31910 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31920 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31930 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
31940 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
31950 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
31960 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31970 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  s16(sqlite3_stmt
31980 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
31990 4c 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20  LITE_API double 
319a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
319b0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
319c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
319d0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
319e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
319f0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
31a00 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49   int iCol);.SQLI
31a10 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
31a20 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
31a30 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
31a40 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31a50 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  l);.SQLITE_API c
31a60 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
31a70 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
31a80 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
31a90 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
31aa0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
31ab0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31ac0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73  _column_text16(s
31ad0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31ae0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
31af0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
31b00 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69  column_type(sqli
31b10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
31b20 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  Col);.SQLITE_API
31b30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a   sqlite3_value *
31b40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
31b50 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  alue(sqlite3_stm
31b60 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a  t*, int iCol);..
31b70 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31b80 44 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72  Destroy A Prepar
31b90 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  ed Statement Obj
31ba0 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ect.**.** ^The s
31bb0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
31bc0 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
31bd0 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61  lled to delete a
31be0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31bf0 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  ment]..** ^If th
31c00 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
31c10 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  aluation of the 
31c20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e  statement encoun
31c30 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a  tered no errors.
31c40 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61  ** or if the sta
31c50 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20  tement is never 
31c60 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20  been evaluated, 
31c70 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e  then sqlite3_fin
31c80 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a  alize() returns.
31c90 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e  ** SQLITE_OK.  ^
31ca0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
31cb0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
31cc0 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69   statement S fai
31cd0 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  led, then.** sql
31ce0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
31cf0 20 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70   returns the app
31d00 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20  ropriate [error 
31d10 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
31d20 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
31d30 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
31d40 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53  lite3_finalize(S
31d50 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  ) routine can be
31d60 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70   called at any p
31d70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74  oint during.** t
31d80 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66  he life cycle of
31d90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
31da0 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f  ment] S:.** befo
31db0 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69  re statement S i
31dc0 73 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64  s ever evaluated
31dd0 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f  , after.** one o
31de0 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20  r more calls to 
31df0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
31e00 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20  ], or after any 
31e10 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  call.** to [sqli
31e20 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61  te3_step()] rega
31e30 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
31e40 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61  r or not the sta
31e50 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f  tement has.** co
31e60 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f  mpleted executio
31e70 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69  n..**.** ^Invoki
31e80 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  ng sqlite3_final
31e90 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20  ize() on a NULL 
31ea0 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72  pointer is a har
31eb0 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a  mless no-op..**.
31ec0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
31ed0 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65  on must finalize
31ee0 20 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64   every [prepared
31ef0 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f   statement] in o
31f00 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a  rder to avoid.**
31f10 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e   resource leaks.
31f20 20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f    It is a grievo
31f30 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65  us error for the
31f40 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20   application to 
31f50 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20  try to use.** a 
31f60 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31f70 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
31f80 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20  been finalized. 
31f90 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72   Any use of a pr
31fa0 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
31fb0 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73  ent after it has
31fc0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20   been finalized 
31fd0 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e  can result in un
31fe0 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75  defined and.** u
31ff0 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76  ndesirable behav
32000 69 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66  ior such as segf
32010 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63  aults and heap c
32020 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51  orruption..*/.SQ
32030 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
32040 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
32050 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
32060 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
32070 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
32080 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
32090 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
320a0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
320b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
320c0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
320d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
320e0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
320f0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
32100 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
32110 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
32120 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
32130 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
32140 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
32150 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
32160 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
32170 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
32180 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
32190 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
321a0 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
321b0 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
321c0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
321d0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
321e0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
321f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
32200 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
32210 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
32220 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
32230 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
32240 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
32250 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
32260 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
32270 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
32280 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
32290 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
322a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
322b0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
322c0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
322d0 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
322e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
322f0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
32300 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
32310 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
32320 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
32330 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
32340 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
32350 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
32360 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
32370 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
32380 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
32390 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
323a0 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
323b0 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
323c0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
323d0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
323e0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
323f0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
32400 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
32410 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
32420 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
32430 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
32440 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
32450 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
32460 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32470 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54  ent] S..*/.SQLIT
32480 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
32490 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f  3_reset(sqlite3_
324a0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
324b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
324c0 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e  reate Or Redefin
324d0 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a  e SQL Functions.
324e0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75  ** KEYWORDS: {fu
324f0 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20  nction creation 
32500 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59  routines}.** KEY
32510 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
32520 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
32530 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59  function}.** KEY
32540 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74  WORDS: {applicat
32550 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
32560 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
32570 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
32580 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20  s (collectively 
32590 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69  known as "functi
325a0 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
325b0 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73  ines").** are us
325c0 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75  ed to add SQL fu
325d0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
325e0 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65  gates or to rede
325f0 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f  fine the behavio
32600 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67  r.** of existing
32610 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
32620 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54  r aggregates.  T
32630 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e  he only differen
32640 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ces between.** t
32650 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
32660 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64  e the text encod
32670 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72  ing expected for
32680 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
32690 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61  arameter (the na
326a0 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  me of the functi
326b0 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  on being created
326c0 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65  ).** and the pre
326d0 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65  sence or absence
326e0 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72   of a destructor
326f0 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a   callback for.**
32700 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32710 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a   data pointer..*
32720 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
32730 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
32740 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
32750 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20  ction] to which 
32760 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74  the SQL.** funct
32770 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64  ion is to be add
32780 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c  ed.  ^If an appl
32790 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72  ication uses mor
327a0 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62  e than one datab
327b0 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
327c0 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69  n then applicati
327d0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
327e0 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65  unctions must be
327f0 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63   added.** to eac
32800 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
32810 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79  ction separately
32820 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63  ..**.** ^The sec
32830 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
32840 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
32850 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f   SQL function to
32860 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a   be created or.*
32870 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54  * redefined.  ^T
32880 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
32890 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64   name is limited
328a0 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e   to 255 bytes in
328b0 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72   a UTF-8.** repr
328c0 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c  esentation, excl
328d0 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72  usive of the zer
328e0 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e  o-terminator.  ^
328f0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61  Note that the na
32900 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d  me.** length lim
32910 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62  it is in UTF-8 b
32920 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63  ytes, not charac
32930 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20  ters nor UTF-16 
32940 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79  bytes.  .** ^Any
32950 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61   attempt to crea
32960 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69  te a function wi
32970 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65  th a longer name
32980 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20  .** will result 
32990 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  in [SQLITE_MISUS
329a0 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65  E] being returne
329b0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  d..**.** ^The th
329c0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e  ird parameter (n
329d0 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e  Arg).** is the n
329e0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
329f0 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20  ts that the SQL 
32a00 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
32a10 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20  ggregate takes. 
32a20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74  ^If this paramet
32a30 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74  er is -1, then t
32a40 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
32a50 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
32a60 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d  may take any num
32a70 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
32a80 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
32a90 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20  he limit.** set 
32aa0 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  by [sqlite3_limi
32ab0 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  t]([SQLITE_LIMIT
32ac0 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e  _FUNCTION_ARG]).
32ad0 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a    If the third.*
32ae0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c  * parameter is l
32af0 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67  ess than -1 or g
32b00 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20  reater than 127 
32b10 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
32b20 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65  r is.** undefine
32b30 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f  d..**.** ^The fo
32b40 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20  urth parameter, 
32b50 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66  eTextRep, specif
32b60 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c  ies what.** [SQL
32b70 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20  ITE_UTF8 | text 
32b80 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53  encoding] this S
32b90 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66  QL function pref
32ba0 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70  ers for.** its p
32bb0 61 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72  arameters.  Ever
32bc0 79 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  y SQL function i
32bd0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
32be0 73 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f  st be able to wo
32bf0 72 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38  rk.** with UTF-8
32c00 2c 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55  , UTF-16le, or U
32c10 54 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f  TF-16be.  But so
32c20 6d 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  me implementatio
32c30 6e 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72  ns may be.** mor
32c40 65 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68  e efficient with
32c50 20 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68   one encoding th
32c60 61 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e  an another.  ^An
32c70 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
32c80 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
32c90 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32ca0 6f 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  on() or sqlite3_
32cb0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
32cc0 36 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  6() multiple.** 
32cd0 74 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73  times with the s
32ce0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74  ame function but
32cf0 20 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20   with different 
32d00 76 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52  values of eTextR
32d10 65 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c  ep..** ^When mul
32d20 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  tiple implementa
32d30 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
32d40 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61  e function are a
32d50 76 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65  vailable, SQLite
32d60 0a 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68  .** will pick th
32d70 65 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c  e one that invol
32d80 76 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  ves the least am
32d90 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e  ount of data con
32da0 76 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74  version..** If t
32db0 68 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73  here is only a s
32dc0 69 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61  ingle implementa
32dd0 74 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20  tion which does 
32de0 6e 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65  not care what te
32df0 78 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69  xt.** encoding i
32e00 73 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65  s used, then the
32e10 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
32e20 20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49   should be [SQLI
32e30 54 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  TE_ANY]..**.** ^
32e40 28 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d  (The fifth param
32e50 65 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74  eter is an arbit
32e60 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54  rary pointer.  T
32e70 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
32e80 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63  n of the.** func
32e90 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63  tion can gain ac
32ea0 63 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69  cess to this poi
32eb0 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69  nter using [sqli
32ec0 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d  te3_user_data()]
32ed0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
32ee0 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e  ixth, seventh an
32ef0 64 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74  d eighth paramet
32f00 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65  ers, xFunc, xSte
32f10 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72  p and xFinal, ar
32f20 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f  e.** pointers to
32f30 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63   C-language func
32f40 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65  tions that imple
32f50 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
32f60 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
32f70 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72  egate. ^A scalar
32f80 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
32f90 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
32fa0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  entation of the 
32fb0 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63  xFunc.** callbac
32fc0 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69  k only; NULL poi
32fd0 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61  nters must be pa
32fe0 73 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65  ssed as the xSte
32ff0 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20  p and xFinal.** 
33000 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20  parameters. ^An 
33010 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
33020 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
33030 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
33040 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e  n of xStep.** an
33050 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c  d xFinal and NUL
33060 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62  L pointer must b
33070 65 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75  e passed for xFu
33080 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61  nc. ^To delete a
33090 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51  n existing.** SQ
330a0 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  L function or ag
330b0 67 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55  gregate, pass NU
330c0 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20  LL pointers for 
330d0 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69  all three functi
330e0 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e  on.** callbacks.
330f0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20  .**.** ^(If the 
33100 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20  ninth parameter 
33110 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  to sqlite3_creat
33120 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
33130 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20  is not NULL,.** 
33140 74 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72  then it is destr
33150 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70  uctor for the ap
33160 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
33170 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20  ointer. .** The 
33180 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e  destructor is in
33190 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66  voked when the f
331a0 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74  unction is delet
331b0 65 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65  ed, either by be
331c0 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65  ing.** overloade
331d0 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61  d or when the da
331e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
331f0 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e  n closes.)^.** ^
33200 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69  The destructor i
33210 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69  s also invoked i
33220 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a  f the call to.**
33230 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33240 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61  function_v2() fa
33250 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68  ils..** ^When th
33260 65 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  e destructor cal
33270 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e  lback of the ten
33280 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
33290 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69  invoked, it.** i
332a0 73 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c  s passed a singl
332b0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
332c0 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
332d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61  e application da
332e0 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77  ta .** pointer w
332f0 68 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66  hich was the fif
33300 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
33310 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33320 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a  unction_v2()..**
33330 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69  .** ^It is permi
33340 74 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72  tted to register
33350 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d   multiple implem
33360 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  entations of the
33370 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f   same.** functio
33380 6e 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65  ns with the same
33390 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65   name but with e
333a0 69 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20  ither differing 
333b0 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72  numbers of.** ar
333c0 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65  guments or diffe
333d0 72 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74  ring preferred t
333e0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20  ext encodings.  
333f0 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
33400 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  .** the implemen
33410 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74  tation that most
33420 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73   closely matches
33430 20 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63   the way in whic
33440 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e  h the.** SQL fun
33450 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20  ction is used.  
33460 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c  ^A function impl
33470 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20  ementation with 
33480 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a  a non-negative.*
33490 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72  * nArg parameter
334a0 20 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74   is a better mat
334b0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
334c0 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
334d0 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61  n with.** a nega
334e0 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66  tive nArg.  ^A f
334f0 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
33500 65 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  e preferred text
33510 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74   encoding.** mat
33520 63 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ches the databas
33530 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20  e encoding is a 
33540 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20  better.** match 
33550 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
33560 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69  where the encodi
33570 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e  ng is different.
33580 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f    .** ^A functio
33590 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
335a0 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20  ding difference 
335b0 69 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36  is between UTF16
335c0 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a  le and UTF16be.*
335d0 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61  * is a closer ma
335e0 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74  tch than a funct
335f0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
33600 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
33610 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  e is.** between 
33620 55 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a  UTF8 and UTF16..
33630 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20  **.** ^Built-in 
33640 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
33650 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e   overloaded by n
33660 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  ew application-d
33670 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73  efined functions
33680 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c  ..**.** ^An appl
33690 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
336a0 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  function is perm
336b0 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74  itted to call ot
336c0 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
336d0 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76  terfaces.  Howev
336e0 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d  er, such calls m
336f0 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65  ust not.** close
33700 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
33710 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e  nnection nor fin
33720 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74  alize or reset t
33730 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  he prepared.** s
33740 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63  tatement in whic
33750 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  h the function i
33760 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51  s running..*/.SQ
33770 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
33780 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33790 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  tion(.  sqlite3 
337a0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
337b0 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
337c0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
337d0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
337e0 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
337f0 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
33800 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
33810 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
33820 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
33830 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
33840 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
33850 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
33860 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
33870 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
33880 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
33890 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
338a0 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
338b0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
338c0 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
338d0 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
338e0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
338f0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
33900 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
33910 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33920 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
33930 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
33940 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
33950 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
33960 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
33970 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
33980 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
33990 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .);.SQLITE_API i
339a0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
339b0 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20  e_function_v2(. 
339c0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
339d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e  const char *zFun
339e0 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
339f0 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
33a00 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
33a10 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
33a20 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
33a30 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
33a40 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
33a50 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
33a60 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
33a70 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
33a80 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
33a90 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
33aa0 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78  ext*),.  void(*x
33ab0 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a  Destroy)(void*).
33ac0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33ad0 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e  EF: Text Encodin
33ae0 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63  gs.**.** These c
33af0 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69  onstant define i
33b00 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61  nteger codes tha
33b10 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20  t represent the 
33b20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20  various.** text 
33b30 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72  encodings suppor
33b40 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a  ted by SQLite..*
33b50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33b60 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20  _UTF8           
33b70 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
33b80 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20  _UTF16LE        
33b90 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
33ba0 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20  _UTF16BE        
33bb0 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
33bc0 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20  _UTF16          
33bd0 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69  4    /* Use nati
33be0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f  ve byte order */
33bf0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33c00 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35  ANY            5
33c10 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
33c20 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f  reate_function o
33c30 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nly */.#define S
33c40 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
33c50 4e 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c  NED  8    /* sql
33c60 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
33c70 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f  ation only */../
33c80 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
33c90 65 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69  eprecated Functi
33ca0 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45  ons.** DEPRECATE
33cb0 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75  D.**.** These fu
33cc0 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70  nctions are [dep
33cd0 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72  recated].  In or
33ce0 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a  der to maintain.
33cf0 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  ** backwards com
33d00 70 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20  patibility with 
33d10 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73  older code, thes
33d20 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74  e functions cont
33d30 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73  inue .** to be s
33d40 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76  upported.  Howev
33d50 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74  er, new applicat
33d60 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69  ions should avoi
33d70 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20  d.** the use of 
33d80 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e  these functions.
33d90 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72    To help encour
33da0 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76  age people to av
33db0 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65  oid.** using the
33dc0 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65  se functions, we
33dd0 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74   are not going t
33de0 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20  o tell you what 
33df0 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e  they do..*/.#ifn
33e00 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
33e10 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54  DEPRECATED.SQLIT
33e20 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50  E_API SQLITE_DEP
33e30 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
33e40 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
33e50 75 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  unt(sqlite3_cont
33e60 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
33e70 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
33e80 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
33e90 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f  expired(sqlite3_
33ea0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  stmt*);.SQLITE_A
33eb0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
33ec0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
33ed0 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e  _transfer_bindin
33ee0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
33ef0 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  , sqlite3_stmt*)
33f00 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
33f10 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
33f20 6e 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61  nt sqlite3_globa
33f30 6c 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b  l_recover(void);
33f40 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
33f50 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
33f60 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
33f70 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
33f80 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
33f90 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
33fa0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
33fb0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
33fc0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
33fd0 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71  64,int),void*,sq
33fe0 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65  lite3_int64);.#e
33ff0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
34000 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20  3REF: Obtaining 
34010 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72  SQL Function Par
34020 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a  ameter Values.**
34030 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61  .** The C-langua
34040 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ge implementatio
34050 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f  n of SQL functio
34060 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
34070 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73  s uses.** this s
34080 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20  et of interface 
34090 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65  routines to acce
340a0 73 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  ss the parameter
340b0 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68   values on.** th
340c0 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67  e function or ag
340d0 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54  gregate..**.** T
340e0 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63  he xFunc (for sc
340f0 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20  alar functions) 
34100 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67  or xStep (for ag
34110 67 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65  gregates) parame
34120 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69  ters.** to [sqli
34130 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34140 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
34150 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34160 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69  ion16()].** defi
34170 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61  ne callbacks tha
34180 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
34190 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
341a0 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a  d aggregates..**
341b0 20 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74   The 3rd paramet
341c0 65 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c  er to these call
341d0 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61  backs is an arra
341e0 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
341f0 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73  .** [protected s
34200 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
34210 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73  jects.  There is
34220 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   one [sqlite3_va
34230 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a  lue] object for.
34240 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65  ** each paramete
34250 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e  r to the SQL fun
34260 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f  ction.  These ro
34270 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
34280 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61  to.** extract va
34290 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73  lues from the [s
342a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
342b0 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  jects..**.** The
342c0 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b  se routines work
342d0 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74   only with [prot
342e0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
342f0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
34300 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
34310 75 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e  use these routin
34320 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74  es on an [unprot
34330 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
34340 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  lue].** object r
34350 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69  esults in undefi
34360 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
34370 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
34380 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69  nes work just li
34390 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  ke the correspon
343a0 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63  ding [column acc
343b0 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a  ess functions].*
343c0 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74  * except that  t
343d0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61  hese routines ta
343e0 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f  ke a single [pro
343f0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
34400 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20  alue] object.** 
34410 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20  pointer instead 
34420 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74  of a [sqlite3_st
34430 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64  mt*] pointer and
34440 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75   an integer colu
34450 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a  mn number..**.**
34460 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
34470 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74  lue_text16() int
34480 65 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20  erface extracts 
34490 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a  a UTF-16 string.
344a0 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  ** in the native
344b0 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74   byte-order of t
344c0 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e  he host machine.
344d0 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
344e0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
344f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
34500 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20  alue_text16le() 
34510 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78  interfaces.** ex
34520 74 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72  tract UTF-16 str
34530 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69  ings as big-endi
34540 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e  an and little-en
34550 64 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c  dian respectivel
34560 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73  y..**.** ^(The s
34570 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d  qlite3_value_num
34580 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65  eric_type() inte
34590 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
345a0 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72  o apply.** numer
345b0 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74  ic affinity to t
345c0 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20  he value.  This 
345d0 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74  means that an at
345e0 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65  tempt is.** made
345f0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
34600 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65  value to an inte
34610 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20  ger or floating 
34620 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75  point.  If.** su
34630 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ch a conversion 
34640 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68  is possible with
34650 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f  out loss of info
34660 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65  rmation (in othe
34670 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74  r.** words, if t
34680 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74  he value is a st
34690 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20  ring that looks 
346a0 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a  like a number).*
346b0 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65  * then the conve
346c0 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d  rsion is perform
346d0 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e  ed.  Otherwise n
346e0 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  o conversion occ
346f0 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  urs..** The [SQL
34700 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
34710 74 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f  tatype] after co
34720 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75  nversion is retu
34730 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c  rned.)^.**.** Pl
34740 65 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75  ease pay particu
34750 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f  lar attention to
34760 20 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74   the fact that t
34770 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72  he pointer retur
34780 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
34790 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
347a0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
347b0 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a  ue_text()], or.*
347c0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
347d0 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62  _text16()] can b
347e0 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79  e invalidated by
347f0 20 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61   a subsequent ca
34800 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
34810 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d  3_value_bytes()]
34820 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
34830 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71  _bytes16()], [sq
34840 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34850 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
34860 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34870 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ()]..**.** These
34880 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
34890 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
348a0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73  e same thread as
348b0 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63  .** the SQL func
348c0 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69  tion that suppli
348d0 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ed the [sqlite3_
348e0 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65  value*] paramete
348f0 72 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  rs..*/.SQLITE_AP
34900 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
34910 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62  lite3_value_blob
34920 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34930 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
34940 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
34950 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
34960 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34970 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
34980 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  ue_bytes16(sqlit
34990 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
349a0 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71  TE_API double sq
349b0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
349c0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
349d0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  *);.SQLITE_API i
349e0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
349f0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
34a00 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34a10 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
34a20 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
34a30 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
34a40 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
34a50 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
34a60 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  ar *sqlite3_valu
34a70 65 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76  e_text(sqlite3_v
34a80 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
34a90 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
34aa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
34ab0 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t16(sqlite3_valu
34ac0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
34ad0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
34ae0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
34af0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
34b00 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
34b10 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
34b20 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62  e3_value_text16b
34b30 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
34b40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
34b50 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
34b60 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
34b70 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ue*);.SQLITE_API
34b80 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c   int sqlite3_val
34b90 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
34ba0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34bb0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
34bc0 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61  : Obtain Aggrega
34bd0 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74  te Function Cont
34be0 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d  ext.**.** Implem
34bf0 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67  entations of agg
34c00 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
34c10 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a  ions use this.**
34c20 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f   routine to allo
34c30 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20  cate memory for 
34c40 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74  storing their st
34c50 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ate..**.** ^The 
34c60 66 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73  first time the s
34c70 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34c80 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f  _context(C,N) ro
34c90 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20  utine is called 
34ca0 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63  .** for a partic
34cb0 75 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66  ular aggregate f
34cc0 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a  unction, SQLite.
34cd0 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f  ** allocates N o
34ce0 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73  f memory, zeroes
34cf0 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79   out that memory
34d00 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20  , and returns a 
34d10 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
34d20 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f  e new memory. ^O
34d30 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  n second and sub
34d40 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
34d50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
34d60 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
34d70 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67  for the same agg
34d80 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20  regate function 
34d90 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65  instance,.** the
34da0 20 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20   same buffer is 
34db0 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74  returned.  Sqlit
34dc0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34dd0 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c  text() is normal
34de0 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63  ly.** called onc
34df0 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63  e for each invoc
34e00 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74  ation of the xSt
34e10 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20  ep callback and 
34e20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74  then one.** last
34e30 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78   time when the x
34e40 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69  Final callback i
34e50 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68  s invoked.  ^(Wh
34e60 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68  en no rows match
34e70 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65  .** an aggregate
34e80 20 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65   query, the xSte
34e90 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  p() callback of 
34ea0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75  the aggregate fu
34eb0 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  nction.** implem
34ec0 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65  entation is neve
34ed0 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69  r called and xFi
34ee0 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20  nal() is called 
34ef0 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a  exactly once..**
34f00 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c   In those cases,
34f10 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
34f20 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67  te_context() mig
34f30 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72  ht be called for
34f40 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69   the.** first ti
34f50 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78  me from within x
34f60 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  Final().)^.**.**
34f70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67   ^The sqlite3_ag
34f80 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34f90 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74  C,N) routine ret
34fa0 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
34fb0 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c  ter if N is.** l
34fc0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
34fd0 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20  l to zero or if 
34fe0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
34ff0 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a  e error occurs..
35000 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75  **.** ^(The amou
35010 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f  nt of space allo
35020 63 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33  cated by sqlite3
35030 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
35040 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65  xt(C,N) is.** de
35050 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20  termined by the 
35060 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66  N parameter on f
35070 69 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20  irst successful 
35080 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20  call.  Changing 
35090 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
350a0 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20  N in subsequent 
350b0 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
350c0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
350d0 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  t() within.** th
350e0 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65  e same aggregate
350f0 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e   function instan
35100 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69  ce will not resi
35110 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a  ze the memory.**
35120 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a   allocation.)^.*
35130 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74  *.** ^SQLite aut
35140 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73  omatically frees
35150 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
35160 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c  cated by .** sql
35170 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
35180 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68  ontext() when th
35190 65 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  e aggregate quer
351a0 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a  y concludes..**.
351b0 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72  ** The first par
351c0 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61  ameter must be a
351d0 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
351e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  [sqlite3_context
351f0 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20   | SQL function 
35200 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73  context] that is
35210 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
35220 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78  eter.** to the x
35230 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63  Step or xFinal c
35240 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20  allback routine 
35250 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20  that implements 
35260 74 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a  the aggregate.**
35270 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
35280 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75   This routine mu
35290 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f  st be called fro
352a0 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61  m the same threa
352b0 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68  d in which.** th
352c0 65 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  e aggregate SQL 
352d0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
352e0 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
352f0 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
35300 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
35310 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
35320 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29  xt*, int nBytes)
35330 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
35340 46 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72  F: User Data For
35350 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
35360 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73   ^The sqlite3_us
35370 65 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66  er_data() interf
35380 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
35390 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
353a0 6e 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68  nter that was th
353b0 65 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61  e pUserData para
353c0 6d 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70  meter (the 5th p
353d0 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20  arameter).** of 
353e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  the [sqlite3_cre
353f0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a  ate_function()].
35400 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
35410 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
35420 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68  6()] routines th
35430 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a  at originally.**
35440 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20   registered the 
35450 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
35460 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ned function..**
35470 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65  .** This routine
35480 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
35490 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
354a0 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a  read in which.**
354b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
354c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
354d0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f  n is running..*/
354e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
354f0 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   *sqlite3_user_d
35500 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
35510 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ext*);../*.** CA
35520 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65  PI3REF: Database
35530 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20   Connection For 
35540 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
35550 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ^The sqlite3_con
35560 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29  text_db_handle()
35570 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
35580 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
35590 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  the pointer to t
355a0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
355b0 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73  nection] (the 1s
355c0 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  t parameter).** 
355d0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
355e0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
355f0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
35600 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35610 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
35620 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
35630 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
35640 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
35650 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
35660 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
35670 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f  qlite3 *sqlite3_
35680 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c  context_db_handl
35690 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
356a0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
356b0 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41  3REF: Function A
356c0 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a  uxiliary Data.**
356d0 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
356e0 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20  g two functions 
356f0 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73  may be used by s
35700 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
35710 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
35720 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
35730 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
35740 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
35750 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
35760 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
35770 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
35780 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
35790 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
357a0 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
357b0 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
357c0 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
357d0 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
357e0 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
357f0 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20   This may.** be 
35800 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c  used, for exampl
35810 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75  e, to add a regu
35820 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d  lar-expression m
35830 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a  atching scalar.*
35840 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20  * function. The 
35850 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e  compiled version
35860 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20   of the regular 
35870 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74  expression is st
35880 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64  ored as.** metad
35890 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77  ata associated w
358a0 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75  ith the SQL valu
358b0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
358c0 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69  regular expressi
358d0 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20  on.** pattern.  
358e0 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67  The compiled reg
358f0 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
35900 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e  can be reused on
35910 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76   multiple.** inv
35920 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
35930 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f  same function so
35940 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e   that the origin
35950 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e  al pattern strin
35960 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65  g.** does not ne
35970 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69  ed to be recompi
35980 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f  led on each invo
35990 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  cation..**.** ^T
359a0 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  he sqlite3_get_a
359b0 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
359c0 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ce returns a poi
359d0 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61  nter to the meta
359e0 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74  data.** associat
359f0 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
35a00 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
35a10 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68  function with th
35a20 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  e Nth argument.*
35a30 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61  * value to the a
35a40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35a50 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66  ed function. ^If
35a60 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73   no metadata has
35a70 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65   been ever.** be
35a80 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e  en set for the N
35a90 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74  th argument of t
35aa0 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20  he function, or 
35ab0 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  if the correspon
35ac0 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  ding.** function
35ad0 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63   parameter has c
35ae0 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65  hanged since the
35af0 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73   meta-data was s
35b00 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  et,.** then sqli
35b10 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
35b20 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
35b30 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
35b40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74  ^The sqlite3_set
35b50 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
35b60 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d  face saves the m
35b70 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74  etadata.** point
35b80 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64  ed to by its 3rd
35b90 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68   parameter as th
35ba0 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74  e metadata for t
35bb0 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d  he N-th.** argum
35bc0 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ent of the appli
35bd0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
35be0 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71  unction.  Subseq
35bf0 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  uent.** calls to
35c00 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
35c10 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74  data() might ret
35c20 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69  urn this data, i
35c30 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20  f it has.** not 
35c40 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a  been destroyed..
35c50 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74  ** ^If it is not
35c60 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69   NULL, SQLite wi
35c70 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65  ll invoke the de
35c80 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63  structor.** func
35c90 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68  tion given by th
35ca0 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
35cb0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
35cc0 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74  uxdata() on.** t
35cd0 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e  he metadata when
35ce0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
35cf0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ng function para
35d00 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a  meter changes.**
35d10 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c   or when the SQL
35d20 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c   statement compl
35d30 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20  etes, whichever 
35d40 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a  comes first..**.
35d50 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65  ** SQLite is fre
35d60 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65  e to call the de
35d70 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f  structor and dro
35d80 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e  p metadata on an
35d90 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
35da0 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61  f any function a
35db0 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68  t any time.  ^Th
35dc0 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65  e only guarantee
35dd0 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20   is that.** the 
35de0 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20  destructor will 
35df0 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65  be called before
35e00 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73   the metadata is
35e10 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20   dropped..**.** 
35e20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d  ^(In practice, m
35e30 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65  etadata is prese
35e40 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e  rved between fun
35e50 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a  ction calls for.
35e60 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74  ** expressions t
35e70 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74  hat are constant
35e80 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65   at compile time
35e90 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20  . This includes 
35ea0 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65  literal.** value
35eb0 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72  s and [parameter
35ec0 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  s].)^.**.** Thes
35ed0 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20  e routines must 
35ee0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74  be called from t
35ef0 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69  he same thread i
35f00 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53  n which.** the S
35f10 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  QL function is r
35f20 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54  unning..*/.SQLIT
35f30 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69  E_API void *sqli
35f40 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
35f50 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35f60 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45  , int N);.SQLITE
35f70 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
35f80 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71  3_set_auxdata(sq
35f90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
35fa0 69 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f  int N, void*, vo
35fb0 69 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  id (*)(void*));.
35fc0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35fd0 3a 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69  : Constants Defi
35fe0 6e 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73  ning Special Des
35ff0 74 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72  tructor Behavior
36000 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65  .**.** These are
36010 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20   special values 
36020 66 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74  for the destruct
36030 6f 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  or that is passe
36040 64 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66  d in as the.** f
36050 69 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f  inal argument to
36060 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
36070 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62  sqlite3_result_b
36080 6c 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  lob()].  ^If the
36090 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61   destructor.** a
360a0 72 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54  rgument is SQLIT
360b0 45 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61  E_STATIC, it mea
360c0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
360d0 65 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63  ent pointer is c
360e0 6f 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77  onstant.** and w
360f0 69 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65  ill never change
36100 2e 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e  .  It does not n
36110 65 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f  eed to be destro
36120 79 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51  yed.  ^The.** SQ
36130 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76  LITE_TRANSIENT v
36140 61 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20  alue means that 
36150 74 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c  the content will
36160 20 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69   likely change i
36170 6e 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75  n.** the near fu
36180 74 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51  ture and that SQ
36190 4c 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65  Lite should make
361a0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
361b0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
361c0 63 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72  content before r
361d0 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
361e0 54 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e  The typedef is n
361f0 65 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b  ecessary to work
36200 20 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73   around problems
36210 20 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43   in certain.** C
36220 2b 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53  ++ compilers.  S
36230 65 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e  ee ticket #2191.
36240 0a 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64  .*/.typedef void
36250 20 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72   (*sqlite3_destr
36260 75 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64  uctor_type)(void
36270 2a 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  *);.#define SQLI
36280 54 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28  TE_STATIC      (
36290 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
362a0 74 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66  tor_type)0).#def
362b0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
362c0 49 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33  IENT   ((sqlite3
362d0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
362e0 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  )-1)../*.** CAPI
362f0 33 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68  3REF: Setting Th
36300 65 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53  e Result Of An S
36310 51 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a  QL Function.**.*
36320 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
36330 20 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65   are used by the
36340 20 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c   xFunc or xFinal
36350 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a   callbacks that.
36360 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c  ** implement SQL
36370 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61   functions and a
36380 67 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a  ggregates.  See.
36390 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
363a0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61  te_function()] a
363b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
363c0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
363d0 0a 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  .** for addition
363e0 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  al information..
363f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63  **.** These func
36400 74 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20  tions work very 
36410 6d 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70  much like the [p
36420 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67  arameter binding
36430 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66  ] family of.** f
36440 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
36450 20 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   bind values to 
36460 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20  host parameters 
36470 69 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74  in prepared stat
36480 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72  ements..** Refer
36490 20 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72   to the [SQL par
364a0 61 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74  ameter] document
364b0 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
364c0 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
364d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
364e0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
364f0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
36500 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
36510 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
36520 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
36530 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42  tion to be the B
36540 4c 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e  LOB whose conten
36550 74 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20  t is pointed.** 
36560 74 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  to by the second
36570 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77   parameter and w
36580 68 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20  hich is N bytes 
36590 6c 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20  long where N is 
365a0 74 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72  the.** third par
365b0 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
365c0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
365d0 74 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74  t_zeroblob() int
365e0 65 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20  erfaces set the 
365f0 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
36600 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
36610 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
36620 20 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61   be a BLOB conta
36630 69 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a  ining all zero.*
36640 2a 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79  * bytes and N by
36650 74 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65  tes in size, whe
36660 72 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75  re N is the valu
36670 65 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72  e of the 2nd par
36680 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ameter..**.** ^T
36690 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
366a0 74 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72  t_double() inter
366b0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
366c0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
366d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
366e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
366f0 62 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  be a floating po
36700 69 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66  int value specif
36710 69 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e  ied.** by its 2n
36720 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a  d argument..**.*
36730 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36740 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
36750 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36760 5f 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74  _error16() funct
36770 69 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68  ions.** cause th
36780 65 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51  e implemented SQ
36790 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68  L function to th
367a0 72 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e  row an exception
367b0 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65  ..** ^SQLite use
367c0 73 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69  s the string poi
367d0 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
367e0 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  * 2nd parameter 
367f0 6f 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  of sqlite3_resul
36800 74 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c  t_error() or sql
36810 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36820 72 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20  r16().** as the 
36830 74 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72  text of an error
36840 20 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69   message.  ^SQLi
36850 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
36860 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
36870 67 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  ge string from s
36880 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36890 72 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20  ror() as UTF-8. 
368a0 5e 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72  ^SQLite.** inter
368b0 70 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67  prets the string
368c0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
368d0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61  sult_error16() a
368e0 73 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69  s UTF-16 in nati
368f0 76 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72  ve.** byte order
36900 2e 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  .  ^If the third
36910 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
36920 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36930 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
36940 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
36950 36 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20  6() is negative 
36960 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
36970 73 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  s as the error.*
36980 2a 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65  * message all te
36990 78 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68  xt up through th
369a0 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
369b0 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
369c0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
369d0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
369e0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a  sult_error() or.
369f0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
36a00 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
36a10 6f 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e  on-negative then
36a20 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68   SQLite takes th
36a30 61 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73  at many.** bytes
36a40 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73   (not characters
36a50 29 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70  ) from the 2nd p
36a60 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
36a70 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
36a80 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
36a90 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e  esult_error() an
36aa0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
36ab0 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f  _error16().** ro
36ac0 75 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72  utines make a pr
36ad0 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
36ae0 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
36af0 74 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74  text before.** t
36b00 68 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e  hey return.  Hen
36b10 63 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ce, the calling 
36b20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61  function can dea
36b30 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f  llocate or.** mo
36b40 64 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66  dify the text af
36b50 74 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20  ter they return 
36b60 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a  without harm..**
36b70 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36b80 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28  sult_error_code(
36b90 29 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67  ) function chang
36ba0 65 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  es the error cod
36bb0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
36bc0 20 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73   SQLite as a res
36bd0 75 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ult of an error 
36be0 69 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20  in a function.  
36bf0 5e 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20  ^By default,.** 
36c00 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69  the error code i
36c10 73 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20  s SQLITE_ERROR. 
36c20 20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63   ^A subsequent c
36c30 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  all to sqlite3_r
36c40 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
36c50 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
36c60 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73  lt_error16() res
36c70 65 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f  ets the error co
36c80 64 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52  de to SQLITE_ERR
36c90 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  OR..**.** ^The s
36ca0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36cb0 72 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74  ror_toobig() int
36cc0 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
36cd0 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
36ce0 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61  .** error indica
36cf0 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69  ting that a stri
36d00 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f  ng or BLOB is to
36d10 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73  o long to repres
36d20 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
36d30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
36d40 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74  rror_nomem() int
36d50 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51  erface causes SQ
36d60 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e  Lite to throw an
36d70 0a 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61  .** error indica
36d80 74 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f  ting that a memo
36d90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
36da0 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  iled..**.** ^The
36db0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36dc0 69 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20  int() interface 
36dd0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
36de0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
36df0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36e00 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
36e10 62 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69  be the 32-bit si
36e20 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
36e30 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
36e40 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
36e50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36e60 5f 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20  _result_int64() 
36e70 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
36e80 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
36e90 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
36ea0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36eb0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65  nction to be the
36ec0 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
36ed0 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20  nteger.** value 
36ee0 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64  given in the 2nd
36ef0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
36f00 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36f10 73 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65  sult_null() inte
36f20 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
36f30 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
36f40 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
36f50 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
36f60 6f 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a  on to be NULL..*
36f70 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36f80 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c  3_result_text(),
36f90 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36fa0 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c  text16(),.** sql
36fb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36fc0 31 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69  16le(), and sqli
36fd0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
36fe0 36 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6be() interfaces
36ff0 0a 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75  .** set the retu
37000 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  rn value of the 
37010 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
37020 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
37030 62 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72  be.** a text str
37040 69 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70  ing which is rep
37050 72 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d  resented as UTF-
37060 38 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65  8, UTF-16 native
37070 20 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20   byte order,.** 
37080 55 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e  UTF-16 little en
37090 64 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20  dian, or UTF-16 
370a0 62 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70  big endian, resp
370b0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51  ectively..** ^SQ
370c0 4c 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74  Lite takes the t
370d0 65 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  ext result from 
370e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
370f0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20  from.** the 2nd 
37100 70 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65  parameter of the
37110 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37120 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
37130 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
37140 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37150 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37160 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
37170 73 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65  s.** is negative
37180 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  , then SQLite ta
37190 6b 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20  kes result text 
371a0 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72  from the 2nd par
371b0 61 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67  ameter.** throug
371c0 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
371d0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
371e0 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d  If the 3rd param
371f0 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
37200 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
37210 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69   interfaces.** i
37220 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20  s non-negative, 
37230 74 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74  then as many byt
37240 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65  es (not characte
37250 72 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a  rs) of the text.
37260 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ** pointed to by
37270 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
37280 65 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20  er are taken as 
37290 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
372a0 64 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74  defined.** funct
372b0 69 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20  ion result.  If 
372c0 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
372d0 72 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  r is non-negativ
372e0 65 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75  e, then it.** mu
372f0 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
37300 66 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73  ffset into the s
37310 74 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20  tring where the 
37320 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
37330 6f 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69  ould.** appear i
37340 66 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65  f the string whe
37350 72 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65  re NUL terminate
37360 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63  d.  If any NUL c
37370 68 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a  haracters occur.
37380 2a 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  ** in the string
37390 20 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65   at a byte offse
373a0 74 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74  t that is less t
373b0 68 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66  han the value of
373c0 20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61   the 3rd.** para
373d0 6d 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  meter, then the 
373e0 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
373f0 20 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d   will contain em
37400 62 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20  bedded NULs and 
37410 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66  the.** result of
37420 20 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65   expressions ope
37430 72 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67  rating on string
37440 73 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20  s with embedded 
37450 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65  NULs is undefine
37460 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  d..** ^If the 4t
37470 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
37480 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
37490 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
374a0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
374b0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
374c0 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
374d0 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
374e0 63 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75  calls that.** fu
374f0 6e 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65  nction as the de
37500 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
37510 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73  text or BLOB res
37520 75 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a  ult when it has.
37530 2a 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e  ** finished usin
37540 67 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a  g that result..*
37550 2a 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61  * ^If the 4th pa
37560 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73  rameter to the s
37570 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37580 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f  xt* interfaces o
37590 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
375a0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
375b0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
375c0 61 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ant SQLITE_STATI
375d0 43 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a  C, then SQLite.*
375e0 2a 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74  * assumes that t
375f0 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20  he text or BLOB 
37600 72 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e  result is in con
37610 73 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20  stant space and 
37620 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79  does not.** copy
37630 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
37640 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f  the parameter no
37650 72 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63  r call a destruc
37660 74 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65  tor on the conte
37670 6e 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61  nt.** when it ha
37680 73 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  s finished using
37690 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
376a0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
376b0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
376c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
376d0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
376e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
376f0 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73  lt_blob is the s
37700 70 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20  pecial constant 
37710 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
37720 0a 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20  .** then SQLite 
37730 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20  makes a copy of 
37740 74 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20  the result into 
37750 73 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66  space obtained f
37760 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  rom.** from [sql
37770 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62  ite3_malloc()] b
37780 65 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73  efore it returns
37790 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
377a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
377b0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
377c0 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  ts the result of
377d0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
377e0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
377f0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70  tion to be a cop
37800 79 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74  y the.** [unprot
37810 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
37820 6c 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63  lue] object spec
37830 69 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64  ified by the 2nd
37840 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68   parameter.  ^Th
37850 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73  e.** sqlite3_res
37860 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65  ult_value() inte
37870 72 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f  rface makes a co
37880 70 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  py of the [sqlit
37890 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20  e3_value].** so 
378a0 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65  that the [sqlite
378b0 33 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69  3_value] specifi
378c0 65 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65  ed in the parame
378d0 74 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f  ter may change o
378e0 72 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61  r.** be dealloca
378f0 74 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65  ted after sqlite
37900 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
37910 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74   returns without
37920 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72   harm..** ^A [pr
37930 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
37940 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61  value] object ma
37950 79 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64  y always be used
37960 20 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e   where an.** [un
37970 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
37980 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
37990 69 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20  is required, so 
379a0 65 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f  either.** kind o
379b0 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  f [sqlite3_value
379c0 5d 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20  ] object can be 
379d0 75 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69  used with this i
379e0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
379f0 49 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  If these routine
37a00 73 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f  s are called fro
37a10 6d 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66  m within the dif
37a20 66 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a  ferent thread.**
37a30 20 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f   than the one co
37a40 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70  ntaining the app
37a50 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
37a60 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72   function that r
37a70 65 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b  eceived.** the [
37a80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d  sqlite3_context]
37a90 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65   pointer, the re
37aa0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
37ab0 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ned..*/.SQLITE_A
37ac0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
37ad0 72 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69  result_blob(sqli
37ae0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
37af0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
37b00 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
37b10 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37b20 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37b30 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
37b40 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
37b50 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
37b60 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37b70 5f 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63  _error(sqlite3_c
37b80 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63  ontext*, const c
37b90 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  har*, int);.SQLI
37ba0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
37bb0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37bc0 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  16(sqlite3_conte
37bd0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
37be0 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  , int);.SQLITE_A
37bf0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
37c00 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
37c10 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  big(sqlite3_cont
37c20 65 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ext*);.SQLITE_AP
37c30 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37c40 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65  esult_error_nome
37c50 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  m(sqlite3_contex
37c60 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  t*);.SQLITE_API 
37c70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
37c80 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73  ult_error_code(s
37c90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37ca0 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
37cb0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37cc0 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65  esult_int(sqlite
37cd0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
37ce0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
37cf0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37d00 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63  _int64(sqlite3_c
37d10 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33  ontext*, sqlite3
37d20 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f  _int64);.SQLITE_
37d30 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
37d40 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c  _result_null(sql
37d50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
37d60 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37d70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37d80 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
37d90 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
37da0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
37db0 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f  void*));.SQLITE_
37dc0 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
37dd0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
37de0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
37df0 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
37e00 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
37e10 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
37e20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37e30 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
37e40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
37e50 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
37e60 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
37e70 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37e80 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37e90 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f  ext16be(sqlite3_
37ea0 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20  context*, const 
37eb0 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28  void*, int,void(
37ec0 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
37ed0 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
37ee0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
37ef0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37f00 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
37f10 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
37f20 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37f30 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69  lt_zeroblob(sqli
37f40 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
37f50 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  t n);../*.** CAP
37f60 49 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65  I3REF: Define Ne
37f70 77 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75  w Collating Sequ
37f80 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ences.**.** ^The
37f90 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64  se functions add
37fa0 2c 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64  , remove, or mod
37fb0 69 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e  ify a [collation
37fc0 5d 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20  ] associated.** 
37fd0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
37fe0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
37ff0 70 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20  pecified as the 
38000 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
38010 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20  **.** ^The name 
38020 6f 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e  of the collation
38030 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
38040 6e 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65  ng.** for sqlite
38050 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
38060 6f 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  on() and sqlite3
38070 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
38080 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20  n_v2().** and a 
38090 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e  UTF-16 string in
380a0 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
380b0 65 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63  er for sqlite3_c
380c0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31  reate_collation1
380d0 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  6()..** ^Collati
380e0 6f 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f  on names that co
380f0 6d 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f  mpare equal acco
38100 72 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65  rding to [sqlite
38110 33 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72  3_strnicmp()] ar
38120 65 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20  e.** considered 
38130 74 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e  to be the same n
38140 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ame..**.** ^(The
38150 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
38160 28 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20  (eTextRep) must 
38170 62 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f  be one of the co
38180 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e  nstants:.** <ul>
38190 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
381a0 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  _UTF8],.** <li> 
381b0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
381c0 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
381d0 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c  E_UTF16BE],.** <
381e0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
381f0 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  6], or.** <li> [
38200 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
38210 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29  GNED]..** </ul>)
38220 5e 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52  ^.** ^The eTextR
38230 65 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65  ep argument dete
38240 72 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64  rmines the encod
38250 69 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70  ing of strings p
38260 61 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  assed.** to the 
38270 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
38280 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61  on callback, xCa
38290 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20  llback..** ^The 
382a0 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61  [SQLITE_UTF16] a
382b0 6e 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  nd [SQLITE_UTF16
382c0 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73  _ALIGNED] values
382d0 20 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a   for eTextRep.**
382e0 20 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74   force strings t
382f0 6f 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20  o be UTF16 with 
38300 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
38310 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  r..** ^The [SQLI
38320 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44  TE_UTF16_ALIGNED
38330 5d 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78  ] value for eTex
38340 74 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69  tRep forces stri
38350 6e 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20  ngs to begin.** 
38360 6f 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20  on an even byte 
38370 61 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e  address..**.** ^
38380 54 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  The fourth argum
38390 65 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e  ent, pArg, is an
383a0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
383b0 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69  a pointer that i
383c0 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f  s passed.** thro
383d0 75 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74  ugh as the first
383e0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
383f0 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
38400 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ion callback..**
38410 0a 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61  .** ^The fifth a
38420 72 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61  rgument, xCallba
38430 63 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ck, is a pointer
38440 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e   to the collatin
38450 67 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e  g function..** ^
38460 4d 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69  Multiple collati
38470 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e  ng functions can
38480 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75   be registered u
38490 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  sing the same na
384a0 6d 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64  me but.** with d
384b0 69 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65  ifferent eTextRe
384c0 70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64  p parameters and
384d0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65   SQLite will use
384e0 20 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75   whichever.** fu
384f0 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
38500 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74  the least amount
38510 20 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f   of data transfo
38520 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20  rmation..** ^If 
38530 74 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72  the xCallback ar
38540 67 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74  gument is NULL t
38550 68 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e  hen the collatin
38560 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a  g function is.**
38570 20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e   deleted.  ^When
38580 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66   all collating f
38590 75 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20  unctions having 
385a0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72  the same name ar
385b0 65 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68  e deleted,.** th
385c0 61 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20  at collation is 
385d0 6e 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65  no longer usable
385e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
385f0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
38600 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
38610 6b 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20  ked with a copy 
38620 6f 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20  of the pArg .** 
38630 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
38640 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74   pointer and wit
38650 68 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e  h two strings in
38660 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70   the encoding sp
38670 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68  ecified.** by th
38680 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d  e eTextRep argum
38690 65 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74  ent.  The collat
386a0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
386b0 74 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69  t return an.** i
386c0 6e 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e  nteger that is n
386d0 65 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f  egative, zero, o
386e0 72 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66  r positive.** if
386f0 20 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e   the first strin
38700 67 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  g is less than, 
38710 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
38720 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65  ater than the se
38730 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74  cond,.** respect
38740 69 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74  ively.  A collat
38750 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
38760 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20  t always return 
38770 74 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a  the same answer.
38780 2a 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d  ** given the sam
38790 65 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77  e inputs.  If tw
387a0 6f 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74  o or more collat
387b0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  ing functions ar
387c0 65 20 72 65 67 69 73 74 65 72 65 64 0a