System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 57b0d8183cab0e3d724ba7250b9bfbd20c1a32ad:


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 33 2e 20 20  ersion 3.7.13.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e  atic.#endif.#ifn
0550: 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23  def SQLITE_API.#
0560: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41   define SQLITE_A
0570: 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a  PI.#endif./*****
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20  ********* Begin 
0590: 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68  file sqliteInt.h
05a0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20  ********/./*.** 
05d0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31  2001 September 1
05e0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  5.**.** The auth
05f0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70  or disclaims cop
0600: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73  yright to this s
0610: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20  ource code.  In 
0620: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65  place of.** a le
0630: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65  gal notice, here
0640: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a   is a blessing:.
0650: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  **.**    May you
0660: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74   do good and not
0670: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79   evil..**    May
0680: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76   you find forgiv
0690: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65  eness for yourse
06a0: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f  lf and forgive o
06b0: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79  thers..**    May
06c0: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c   you share freel
06d0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20  y, never taking 
06e0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69  more than you gi
06f0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ve..**.*********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0740: 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74  .** Internal int
0750: 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f  erface definitio
0760: 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a  ns for SQLite..*
0770: 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51  *.*/.#ifndef _SQ
0780: 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69  LITEINT_H_.#defi
0790: 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f  ne _SQLITEINT_H_
07a0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64  ../*.** These #d
07b0: 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e  efines should en
07c0: 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73  able >2GB file s
07d0: 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20  upport on POSIX 
07e0: 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  if the.** underl
07f0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
0800: 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69  ystem supports i
0810: 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61  t.  If the OS la
0820: 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c  cks.** large fil
0830: 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66  e support, or if
0840: 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f   the OS is windo
0850: 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64  ws, these should
0860: 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   be no-ops..**.*
0870: 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20  * Ticket #2739: 
0880: 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f   The _LARGEFILE_
0890: 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73  SOURCE macro mus
08a0: 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20  t appear before 
08b0: 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69  any.** system #i
08c0: 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c  ncludes.  Hence,
08d0: 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63   this block of c
08e0: 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20  ode must be the 
08f0: 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f  very first.** co
0900: 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65  de in all source
0910: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61   files..**.** La
0920: 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74  rge file support
0930: 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64   can be disabled
0940: 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c   using the -DSQL
0950: 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20  ITE_DISABLE_LFS 
0960: 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65  switch.** on the
0970: 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e   compiler comman
0980: 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73  d line.  This is
0990: 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f   necessary if yo
09a0: 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a  u are compiling.
09b0: 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d  ** on a recent m
09c0: 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20  achine (ex: Red 
09d0: 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75  Hat 7.2) but you
09e0: 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20   want your code 
09f0: 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e  to work.** on an
0a00: 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28   older machine (
0a10: 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29  ex: Red Hat 6.0)
0a20: 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c  .  If you compil
0a30: 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32  e on Red Hat 7.2
0a40: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73  .** without this
0a50: 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20   option, LFS is 
0a60: 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53  enable.  But LFS
0a70: 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20   does not exist 
0a80: 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a  in the kernel.**
0a90: 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c   in Red Hat 6.0,
0aa0: 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e   so the code won
0ab0: 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c  't work.  Hence,
0ac0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e   for maximum bin
0ad0: 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69  ary.** portabili
0ae0: 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d  ty you should om
0af0: 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 69  it LFS..**.** Si
0b00: 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f  milar is true fo
0b10: 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53  r Mac OS X.  LFS
0b20: 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74   is only support
0b30: 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39  ed on Mac OS X 9
0b40: 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23   and later..*/.#
0b50: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49  ifndef SQLITE_DI
0b60: 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69  SABLE_LFS.# defi
0b70: 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20  ne _LARGE_FILE  
0b80: 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20       1.# ifndef 
0b90: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54  _FILE_OFFSET_BIT
0ba0: 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49  S.#   define _FI
0bb0: 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36  LE_OFFSET_BITS 6
0bc0: 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69  4.# endif.# defi
0bd0: 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f  ne _LARGEFILE_SO
0be0: 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f  URCE 1.#endif../
0bf0: 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65  *.** Include the
0c00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 68   configuration h
0c10: 65 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 20  eader output by 
0c20: 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 77  'configure' if w
0c30: 65 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  e're using the.*
0c40: 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 64  * autoconf-based
0c50: 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 66   build.*/.#ifdef
0c60: 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 4f   _HAVE_SQLITE_CO
0c70: 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 20  NFIG_H.#include 
0c80: 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 69  "config.h".#endi
0c90: 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  f../************
0ca0: 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74  ** Include sqlit
0cb0: 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 20  eLimit.h in the 
0cc0: 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65  middle of sqlite
0cd0: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  Int.h **********
0ce0: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
0cf0: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71  ** Begin file sq
0d00: 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a  liteLimit.h ****
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d30: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d 61  */./*.** 2007 Ma
0d40: 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  y 7.**.** The au
0d50: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
0d60: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
0d70: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
0d80: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0d90: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0da0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0db0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0dc0: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0dd0: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0de0: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0df0: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0e00: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0e10: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0e20: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
0e30: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
0e40: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
0e50: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ea0: 2a 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 66  **.** .** This f
0eb0: 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 69  ile defines vari
0ec0: 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 68  ous limits of wh
0ed0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 72  at SQLite can pr
0ee0: 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ocess..*/../*.**
0ef0: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   The maximum len
0f00: 67 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f 72  gth of a TEXT or
0f10: 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 20   BLOB in bytes. 
0f20: 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 6c    This also.** l
0f30: 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f  imits the size o
0f40: 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 62  f a row in a tab
0f50: 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a 0a  le or index..**.
0f60: 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d 69  ** The hard limi
0f70: 74 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 79  t is the ability
0f80: 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
0f90: 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 74  ned integer.** t
0fa0: 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a 65  o count the size
0fb0: 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 37  : 2^31-1 or 2147
0fc0: 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 64  483647..*/.#ifnd
0fd0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  ef SQLITE_MAX_LE
0fe0: 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51  NGTH.# define SQ
0ff0: 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 20  LITE_MAX_LENGTH 
1000: 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 69  1000000000.#endi
1010: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 73  f../*.** This is
1020: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1030: 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 20  ber of.**.**    
1040: 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  * Columns in a t
1050: 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c  able.**    * Col
1060: 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
1070: 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e 73  .**    * Columns
1080: 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 20   in a view.**   
1090: 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20   * Terms in the 
10a0: 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 6e  SET clause of an
10b0: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
10c0: 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20  t.**    * Terms 
10d0: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
10e0: 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
10f0: 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a 20  atement.**    * 
1100: 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 4f  Terms in the GRO
1110: 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 42  UP BY or ORDER B
1120: 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 53  Y clauses of a S
1130: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1140: 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69  .**    * Terms i
1150: 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61  n the VALUES cla
1160: 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54  use of an INSERT
1170: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
1180: 20 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20   The hard upper 
1190: 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 32  limit here is 32
11a0: 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 62  676.  Most datab
11b0: 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c 0a  ase people will.
11c0: 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 74  ** tell you that
11d0: 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d 61   in a well-norma
11e0: 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c 20  lized database, 
11f0: 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f 75  you usually shou
1200: 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 6d  ld.** not have m
1210: 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 6e  ore than a dozen
1220: 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 69   or so columns i
1230: 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 6e  n any table.  An
1240: 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 20  d if.** that is 
1250: 74 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 20  the case, there 
1260: 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 68  is no point in h
1270: 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aving more than 
1280: 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 76  a few.** dozen v
1290: 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 20  alues in any of 
12a0: 74 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 74  the other situat
12b0: 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61  ions described a
12c0: 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  bove..*/.#ifndef
12d0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55   SQLITE_MAX_COLU
12e0: 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  MN.# define SQLI
12f0: 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 30  TE_MAX_COLUMN 20
1300: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1310: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   The maximum len
1320: 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  gth of a single 
1330: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1340: 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 74   bytes..**.** It
1350: 20 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20   used to be the 
1360: 63 61 73 65 20 74 68 61 74 20 73 65 74 74 69 6e  case that settin
1370: 67 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f 20  g this value to 
1380: 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 75  zero would.** tu
1390: 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 66  rn the limit off
13a0: 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c 6f  .  That is no lo
13b0: 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 69  nger true.  It i
13c0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a 2a  s not possible.*
13d0: 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 6c  * to turn this l
13e0: 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 66  imit off..*/.#if
13f0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1400: 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 66  SQL_LENGTH.# def
1410: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53  ine SQLITE_MAX_S
1420: 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 30  QL_LENGTH 100000
1430: 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  0000.#endif../*.
1440: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  ** The maximum d
1450: 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 65  epth of an expre
1460: 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 73  ssion tree. This
1470: 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 0a   is limited to .
1480: 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62  ** some extent b
1490: 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c  y SQLITE_MAX_SQL
14a0: 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f 6d  _LENGTH. But som
14b0: 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 20  etime you might 
14c0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 63  .** want to plac
14d0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c 69  e more severe li
14e0: 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  mits on the comp
14f0: 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a 2a  lexity of an .**
1500: 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a 0a   expression..**.
1510: 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20  ** A value of 0 
1520: 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 61  used to mean tha
1530: 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
1540: 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a 2a  not enforced..**
1550: 20 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f 20   But that is no 
1560: 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 68  longer true.  Th
1570: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 73  e limit is now s
1580: 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 64  trictly enforced
1590: 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 73  .** at all times
15a0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
15b0: 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50  ITE_MAX_EXPR_DEP
15c0: 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  TH.# define SQLI
15d0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54  TE_MAX_EXPR_DEPT
15e0: 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f  H 1000.#endif../
15f0: 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d  *.** The maximum
1600: 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
1610: 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
1620: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1630: 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 6e  .** The code gen
1640: 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 6f  erator for compo
1650: 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1660: 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a 2a  ments does one.*
1670: 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 72  * level of recur
1680: 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 65  sion for each te
1690: 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 65  rm.  A stack ove
16a0: 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c 74  rflow can result
16b0: 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 65  .** if the numbe
16c0: 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 6f  r of terms is to
16d0: 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 61  o large.  In pra
16e0: 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c 0a  ctice, most SQL.
16f0: 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f 72  ** never has mor
1700: 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 65  e than 3 or 4 te
1710: 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c 75  rms.  Use a valu
1720: 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 6c  e of 0 to disabl
1730: 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 6f  e.** any limit o
1740: 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
1750: 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1760: 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a 23  unt SELECT..*/.#
1770: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41  ifndef SQLITE_MA
1780: 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  X_COMPOUND_SELEC
1790: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  T.# define SQLIT
17a0: 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53  E_MAX_COMPOUND_S
17b0: 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 66  ELECT 500.#endif
17c0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69  ../*.** The maxi
17d0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70  mum number of op
17e0: 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 20  codes in a VDBE 
17f0: 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 20  program..** Not 
1800: 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 63  currently enforc
1810: 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  ed..*/.#ifndef S
1820: 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f  QLITE_MAX_VDBE_O
1830: 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  P.# define SQLIT
1840: 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 35  E_MAX_VDBE_OP 25
1850: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  000.#endif../*.*
1860: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  * The maximum nu
1870: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
1880: 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e 63  s to an SQL func
1890: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  tion..*/.#ifndef
18a0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43   SQLITE_MAX_FUNC
18b0: 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 6e  TION_ARG.# defin
18c0: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e  e SQLITE_MAX_FUN
18d0: 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 65  CTION_ARG 127.#e
18e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  ndif../*.** The 
18f0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1900: 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 65  f in-memory page
1910: 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65  s to use for the
1920: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a 2a   main database.*
1930: 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 20  * table and for 
1940: 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 73  temporary tables
1950: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45  .  The SQLITE_DE
1960: 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45  FAULT_CACHE_SIZE
1970: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
1980: 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 45  TE_DEFAULT_CACHE
1990: 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53  _SIZE.# define S
19a0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41  QLITE_DEFAULT_CA
19b0: 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a 23  CHE_SIZE  2000.#
19c0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
19d0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 4d  LITE_DEFAULT_TEM
19e0: 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 64  P_CACHE_SIZE.# d
19f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
1a00: 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 5f  AULT_TEMP_CACHE_
1a10: 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 66  SIZE  500.#endif
1a20: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ../*.** The defa
1a30: 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 72  ult number of fr
1a40: 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c 61  ames to accumula
1a50: 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69  te in the log fi
1a60: 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 65  le before.** che
1a70: 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 64  ckpointing the d
1a80: 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d  atabase in WAL m
1a90: 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ode..*/.#ifndef 
1aa0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57  SQLITE_DEFAULT_W
1ab0: 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e  AL_AUTOCHECKPOIN
1ac0: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  T.# define SQLIT
1ad0: 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55  E_DEFAULT_WAL_AU
1ae0: 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 30  TOCHECKPOINT  10
1af0: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1b00: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   The maximum num
1b10: 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20  ber of attached 
1b20: 64 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 73  databases.  This
1b30: 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
1b40: 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 54   0.** and 62.  T
1b50: 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  he upper bound o
1b60: 6e 20 36 32 20 69 73 20 62 65 63 61 75 73 65 20  n 62 is because 
1b70: 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  a 64-bit integer
1b80: 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 73   bitmap.** is us
1b90: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
1ba0: 20 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 20   track attached 
1bb0: 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 69  databases..*/.#i
1bc0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1bd0: 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 69  _ATTACHED.# defi
1be0: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54  ne SQLITE_MAX_AT
1bf0: 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 66  TACHED 10.#endif
1c00: 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78  .../*.** The max
1c10: 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 20  imum value of a 
1c20: 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 68  ?nnn wildcard th
1c30: 61 74 20 74 68 65 20 70 61 72 73 65 72 20 77 69  at the parser wi
1c40: 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 69  ll accept..*/.#i
1c50: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1c60: 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1c70: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1c80: 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
1c90: 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 0a  MBER 999.#endif.
1ca0: 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 65  ./* Maximum page
1cb0: 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 65   size.  The uppe
1cc0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 20  r bound on this 
1cd0: 76 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e 20  value is 65536. 
1ce0: 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a 2a   This a limit.**
1cf0: 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 20   imposed by the 
1d00: 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f 66  use of 16-bit of
1d10: 66 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 63  fsets within eac
1d20: 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 61  h page..**.** Ea
1d30: 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  rlier versions o
1d40: 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 64  f SQLite allowed
1d50: 20 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 61   the user to cha
1d60: 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 61  nge this value a
1d70: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t.** compile tim
1d80: 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c 6f  e. This is no lo
1d90: 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c 20  nger permitted, 
1da0: 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 74  on the grounds t
1db0: 68 61 74 20 69 74 20 63 72 65 61 74 65 73 0a 2a  hat it creates.*
1dc0: 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 74  * a library that
1dd0: 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 20   is technically 
1de0: 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 74  incompatible wit
1df0: 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 72  h an SQLite libr
1e00: 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  ary .** compiled
1e10: 20 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e   with a differen
1e20: 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 72  t limit. If a pr
1e30: 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 20  ocess operating 
1e40: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  on a database .*
1e50: 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 69  * with a page-si
1e60: 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 65  ze of 65536 byte
1e70: 73 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e 20  s crashes, then 
1e80: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 53  an instance of S
1e90: 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 6c  QLite .** compil
1ea0: 65 64 20 77 69 74 68 20 74 68 65 20 64 65 66 61  ed with the defa
1eb0: 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c 69  ult page-size li
1ec0: 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  mit will not be 
1ed0: 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b  able to rollback
1ee0: 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 64   .** the aborted
1ef0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
1f00: 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 6f  is could lead to
1f10: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
1f20: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  tion..*/.#ifdef 
1f30: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
1f40: 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 4c  SIZE.# undef SQL
1f50: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a  ITE_MAX_PAGE_SIZ
1f60: 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  E.#endif.#define
1f70: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45   SQLITE_MAX_PAGE
1f80: 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f 2a  _SIZE 65536.../*
1f90: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
1fa0: 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 61  size of a databa
1fb0: 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 6e  se page..*/.#ifn
1fc0: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55  def SQLITE_DEFAU
1fd0: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64  LT_PAGE_SIZE.# d
1fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
1ff0: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 31  AULT_PAGE_SIZE 1
2000: 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 53  024.#endif.#if S
2010: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41  QLITE_DEFAULT_PA
2020: 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f 4d  GE_SIZE>SQLITE_M
2030: 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 75  AX_PAGE_SIZE.# u
2040: 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41  ndef SQLITE_DEFA
2050: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20  ULT_PAGE_SIZE.# 
2060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
2070: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20  FAULT_PAGE_SIZE 
2080: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
2090: 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  SIZE.#endif../*.
20a0: 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 69  ** Ordinarily, i
20b0: 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 78  f no value is ex
20c0: 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 65  plicitly provide
20d0: 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 65  d, SQLite create
20e0: 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 77  s databases.** w
20f0: 69 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 51  ith page size SQ
2100: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47  LITE_DEFAULT_PAG
2110: 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 2c  E_SIZE. However,
2120: 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 69   based on certai
2130: 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 72  n.** device char
2140: 61 63 74 65 72 69 73 74 69 63 73 20 28 73 65 63  acteristics (sec
2150: 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 6f  tor-size and ato
2160: 6d 69 63 20 77 72 69 74 65 28 29 20 73 75 70 70  mic write() supp
2170: 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  ort),.** SQLite 
2180: 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 72  may choose a lar
2190: 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 20  ger value. This 
21a0: 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 20  constant is the 
21b0: 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a 2a  maximum value.**
21c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 6f   SQLite will cho
21d0: 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e 0a  ose on its own..
21e0: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
21f0: 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41  E_MAX_DEFAULT_PA
2200: 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65  GE_SIZE.# define
2210: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41   SQLITE_MAX_DEFA
2220: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 31  ULT_PAGE_SIZE 81
2230: 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51  92.#endif.#if SQ
2240: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54  LITE_MAX_DEFAULT
2250: 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54  _PAGE_SIZE>SQLIT
2260: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a  E_MAX_PAGE_SIZE.
2270: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  # undef SQLITE_M
2280: 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f  AX_DEFAULT_PAGE_
2290: 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51  SIZE.# define SQ
22a0: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54  LITE_MAX_DEFAULT
22b0: 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 54  _PAGE_SIZE SQLIT
22c0: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a  E_MAX_PAGE_SIZE.
22d0: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 4d  #endif.../*.** M
22e0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
22f0: 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 61   pages in one da
2300: 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
2310: 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c 6c  ** This is reall
2320: 79 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 75  y just the defau
2330: 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
2340: 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20   max_page_count 
2350: 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 20  pragma..** This 
2360: 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f 77  value can be low
2370: 65 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 29  ered (or raised)
2380: 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
2390: 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 6d  ng that the.** m
23a0: 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d 61  ax_page_count ma
23b0: 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  cro..*/.#ifndef 
23c0: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
23d0: 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 53  COUNT.# define S
23e0: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43  QLITE_MAX_PAGE_C
23f0: 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 0a  OUNT 1073741823.
2400: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61  #endif../*.** Ma
2410: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 6e  ximum length (in
2420: 20 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 70   bytes) of the p
2430: 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b 45  attern in a LIKE
2440: 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 72   or GLOB.** oper
2450: 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  ator..*/.#ifndef
2460: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45   SQLITE_MAX_LIKE
2470: 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 0a  _PATTERN_LENGTH.
2480: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2490: 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MAX_LIKE_PATTERN
24a0: 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 65  _LENGTH 50000.#e
24b0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 69  ndif../*.** Maxi
24c0: 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
24d0: 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
24e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 6c  ers..**.** A val
24f0: 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 68  ue of 1 means th
2500: 61 74 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  at a trigger pro
2510: 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 65  gram will not be
2520: 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 0a   able to itself.
2530: 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 67  ** fire any trig
2540: 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f 66  gers. A value of
2550: 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f   0 means that no
2560: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
2570: 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 79  s at all .** may
2580: 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a 2f   be executed..*/
2590: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
25a0: 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MAX_TRIGGER_DEPT
25b0: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  H.# define SQLIT
25c0: 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45  E_MAX_TRIGGER_DE
25d0: 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a  PTH 1000.#endif.
25e0: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
25f0: 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c 69   End of sqliteLi
2600: 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  mit.h **********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
2630: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
2640: 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72   Continuing wher
2650: 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e  e we left off in
2660: 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a   sqliteInt.h ***
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
2680: 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 69  ../* Disable nui
2690: 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 6f  sance warnings o
26a0: 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 6c  n Borland compil
26b0: 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e  ers */.#if defin
26c0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
26d0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 72  .#pragma warn -r
26e0: 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 6c  ch /* unreachabl
26f0: 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 6d  e code */.#pragm
2700: 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 43  a warn -ccc /* C
2710: 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 61  ondition is alwa
2720: 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65  ys true or false
2730: 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 6e   */.#pragma warn
2740: 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e 65   -aus /* Assigne
2750: 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 72  d value is never
2760: 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d 61   used */.#pragma
2770: 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 6f   warn -csu /* Co
2780: 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 61  mparing signed a
2790: 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a 23  nd unsigned */.#
27a0: 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 61  pragma warn -spa
27b0: 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 70   /* Suspicious p
27c0: 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 69  ointer arithmeti
27d0: 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20  c */.#endif../* 
27e0: 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f  Needed for vario
27f0: 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e  us definitions..
2800: 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 4e  . */.#ifndef _GN
2810: 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 6e  U_SOURCE.# defin
2820: 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65  e _GNU_SOURCE.#e
2830: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c  ndif../*.** Incl
2840: 75 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61  ude standard hea
2850: 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63  der files as nec
2860: 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66  essary.*/.#ifdef
2870: 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23   HAVE_STDINT_H.#
2880: 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e  include <stdint.
2890: 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66  h>.#endif.#ifdef
28a0: 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48   HAVE_INTTYPES_H
28b0: 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79  .#include <intty
28c0: 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f  pes.h>.#endif../
28d0: 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
28e0: 6e 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  ng macros are us
28f0: 65 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74  ed to cast point
2900: 65 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20  ers to integers 
2910: 61 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  and.** integers 
2920: 74 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68  to pointers.  Th
2930: 65 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69  e way you do thi
2940: 73 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  s varies from on
2950: 65 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f  e compiler.** to
2960: 20 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65   the next, so we
2970: 20 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20   have developed 
2980: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65  the following se
2990: 74 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65  t of #if stateme
29a0: 6e 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61  nts.** to genera
29b0: 74 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d  te appropriate m
29c0: 61 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65  acros for a wide
29d0: 20 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c   range of compil
29e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ers..**.** The c
29f0: 6f 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 61  orrect "ANSI" wa
2a00: 79 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20  y to do this is 
2a10: 74 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 74  to use the intpt
2a20: 72 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e  r_t type. .** Un
2a30: 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61  fortunately, tha
2a40: 74 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74  t typedef is not
2a50: 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c   available on al
2a60: 6c 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a  l compilers, or.
2a70: 2a 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 69  ** if it is avai
2a80: 6c 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72  lable, it requir
2a90: 65 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f  es an #include o
2aa0: 66 20 73 70 65 63 69 66 69 63 20 68 65 61 64 65  f specific heade
2ab0: 72 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20  rs.** that vary 
2ac0: 66 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65  from one machine
2ad0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a   to the next..**
2ae0: 0a 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30  .** Ticket #3860
2af0: 3a 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d  :  The llvm-gcc-
2b00: 34 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f  4.2 compiler fro
2b10: 6d 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f  m Apple chokes o
2b20: 6e 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a  n.** the ((void*
2b30: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29  )&((char*)0)[X])
2b40: 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74   construct.  But
2b50: 20 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20   MSVC chokes on 
2b60: 28 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a  ((void*)(X))..**
2b70: 20 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64   So we have to d
2b80: 65 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73  efine the macros
2b90: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61   in different wa
2ba0: 79 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ys depending on 
2bb0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e  the.** compiler.
2bc0: 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28  .*/.#if defined(
2bd0: 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f  __PTRDIFF_TYPE__
2be0: 29 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20  )  /* This case 
2bf0: 73 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20  should work for 
2c00: 47 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20  GCC */.# define 
2c10: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54  SQLITE_INT_TO_PT
2c20: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f  R(X)  ((void*)(_
2c30: 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29  _PTRDIFF_TYPE__)
2c40: 28 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51  (X)).# define SQ
2c50: 4c 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28  LITE_PTR_TO_INT(
2c60: 58 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52  X)  ((int)(__PTR
2c70: 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29  DIFF_TYPE__)(X))
2c80: 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28  .#elif !defined(
2c90: 5f 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20  __GNUC__)       
2ca0: 2f 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d  /* Works for com
2cb0: 70 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61  pilers other tha
2cc0: 6e 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69  n LLVM */.# defi
2cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f  ne SQLITE_INT_TO
2ce0: 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a  _PTR(X)  ((void*
2cf0: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29  )&((char*)0)[X])
2d00: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2d10: 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20  _PTR_TO_INT(X)  
2d20: 28 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58  ((int)(((char*)X
2d30: 29 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c  )-(char*)0)).#el
2d40: 69 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f  if defined(HAVE_
2d50: 53 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55  STDINT_H)   /* U
2d60: 73 65 20 74 68 69 73 20 63 61 73 65 20 69 66 20  se this case if 
2d70: 77 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 61  we have ANSI hea
2d80: 64 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65  ders */.# define
2d90: 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50   SQLITE_INT_TO_P
2da0: 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28  TR(X)  ((void*)(
2db0: 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20  intptr_t)(X)).# 
2dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54  define SQLITE_PT
2dd0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69  R_TO_INT(X)  ((i
2de0: 6e 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29  nt)(intptr_t)(X)
2df0: 29 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 20  ).#else         
2e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e10: 20 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20   /* Generates a 
2e20: 77 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74  warning - but it
2e30: 20 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f   always works */
2e40: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2e50: 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20  _INT_TO_PTR(X)  
2e60: 28 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64  ((void*)(X)).# d
2e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52  efine SQLITE_PTR
2e80: 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e  _TO_INT(X)  ((in
2e90: 74 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f  t)(X)).#endif../
2ea0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
2eb0: 54 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f  THREADSAFE macro
2ec0: 20 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 64   must be defined
2ed0: 20 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a   as 0, 1, or 2..
2ee0: 2a 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78  ** 0 means mutex
2ef0: 65 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74  es are permanent
2f00: 6c 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74  ly disable and t
2f10: 68 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65  he library is ne
2f20: 76 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66  ver.** threadsaf
2f30: 65 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20  e.  1 means the 
2f40: 6c 69 62 72 61 72 79 20 69 73 20 73 65 72 69 61  library is seria
2f50: 6c 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 74  lized which is t
2f60: 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65  he highest.** le
2f70: 76 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66  vel of threadsaf
2f80: 65 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68  ety.  2 means th
2f90: 65 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c 74  e libary is mult
2fa0: 69 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74  ithreaded - mult
2fb0: 69 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20  iple.** threads 
2fc0: 63 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61  can use SQLite a
2fd0: 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
2fe0: 20 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20   threads try to 
2ff0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
3000: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3010: 69 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  ion at the same 
3020: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65  time..**.** Olde
3030: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
3040: 4c 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74  Lite used an opt
3050: 69 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45  ional THREADSAFE
3060: 20 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75   macro..** We su
3070: 70 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c  pport that for l
3080: 65 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64  egacy..*/.#if !d
3090: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48  efined(SQLITE_TH
30a0: 52 45 41 44 53 41 46 45 29 0a 23 69 66 20 64 65  READSAFE).#if de
30b0: 66 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45  fined(THREADSAFE
30c0: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  ).# define SQLIT
30d0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 54 48 52  E_THREADSAFE THR
30e0: 45 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23 20  EADSAFE.#else.# 
30f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 48  define SQLITE_TH
3100: 52 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49 4d  READSAFE 1 /* IM
3110: 50 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30 39  P: R-07272-22309
3120: 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69   */.#endif.#endi
3130: 66 0a 0a 2f 2a 0a 2a 2a 20 50 6f 77 65 72 73 61  f../*.** Powersa
3140: 66 65 20 6f 76 65 72 77 72 69 74 65 20 69 73 20  fe overwrite is 
3150: 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
3160: 42 75 74 20 63 61 6e 20 62 65 20 74 75 72 6e 65  But can be turne
3170: 64 20 6f 66 66 20 75 73 69 6e 67 0a 2a 2a 20 74  d off using.** t
3180: 68 65 20 2d 44 53 51 4c 49 54 45 5f 50 4f 57 45  he -DSQLITE_POWE
3190: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 3d  RSAFE_OVERWRITE=
31a0: 30 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 6f  0 command-line o
31b0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ption..*/.#ifnde
31c0: 66 20 53 51 4c 49 54 45 5f 50 4f 57 45 52 53 41  f SQLITE_POWERSA
31d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 0a 23 20 64  FE_OVERWRITE.# d
31e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 4f 57  efine SQLITE_POW
31f0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
3200: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a   1.#endif../*.**
3210: 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46 41   The SQLITE_DEFA
3220: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 20 6d 61  ULT_MEMSTATUS ma
3230: 63 72 6f 20 6d 75 73 74 20 62 65 20 64 65 66 69  cro must be defi
3240: 6e 65 64 20 61 73 20 65 69 74 68 65 72 20 30 20  ned as either 0 
3250: 6f 72 20 31 2e 0a 2a 2a 20 49 74 20 64 65 74 65  or 1..** It dete
3260: 72 6d 69 6e 65 73 20 77 68 65 74 68 65 72 20 6f  rmines whether o
3270: 72 20 6e 6f 74 20 74 68 65 20 66 65 61 74 75 72  r not the featur
3280: 65 73 20 72 65 6c 61 74 65 64 20 74 6f 20 0a 2a  es related to .*
3290: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
32a0: 4d 45 4d 53 54 41 54 55 53 20 61 72 65 20 61 76  MEMSTATUS are av
32b0: 61 69 6c 61 62 6c 65 20 62 79 20 64 65 66 61 75  ailable by defau
32c0: 6c 74 20 6f 72 20 6e 6f 74 2e 20 54 68 69 73 20  lt or not. This 
32d0: 76 61 6c 75 65 20 63 61 6e 0a 2a 2a 20 62 65 20  value can.** be 
32e0: 6f 76 65 72 72 69 64 64 65 6e 20 61 74 20 72 75  overridden at ru
32f0: 6e 74 69 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ntime using the 
3300: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
3310: 20 41 50 49 2e 0a 2a 2f 0a 23 69 66 20 21 64 65   API..*/.#if !de
3320: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 46  fined(SQLITE_DEF
3330: 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 29 0a  AULT_MEMSTATUS).
3340: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
3350: 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
3360: 53 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  S 1.#endif../*.*
3370: 2a 20 45 78 61 63 74 6c 79 20 6f 6e 65 20 6f 66  * Exactly one of
3380: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d   the following m
3390: 61 63 72 6f 73 20 6d 75 73 74 20 62 65 20 64 65  acros must be de
33a0: 66 69 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  fined in order t
33b0: 6f 0a 2a 2a 20 73 70 65 63 69 66 79 20 77 68 69  o.** specify whi
33c0: 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ch memory alloca
33d0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 74  tion subsystem t
33e0: 6f 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 20 20 20  o use..**.**    
33f0: 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d   SQLITE_SYSTEM_M
3400: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 20 2f  ALLOC          /
3410: 2f 20 55 73 65 20 6e 6f 72 6d 61 6c 20 73 79 73  / Use normal sys
3420: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 20  tem malloc().** 
3430: 20 20 20 20 53 51 4c 49 54 45 5f 57 49 4e 33 32      SQLITE_WIN32
3440: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20  _MALLOC         
3450: 20 20 2f 2f 20 55 73 65 20 57 69 6e 33 32 20 6e    // Use Win32 n
3460: 61 74 69 76 65 20 68 65 61 70 20 41 50 49 0a 2a  ative heap API.*
3470: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4d 45 4d  *     SQLITE_MEM
3480: 44 45 42 55 47 20 20 20 20 20 20 20 20 20 20 20  DEBUG           
3490: 20 20 20 20 2f 2f 20 44 65 62 75 67 67 69 6e 67      // Debugging
34a0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 79 73 74   version of syst
34b0: 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a 2a  em malloc().**.*
34c0: 2a 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69 66  * On Windows, if
34d0: 20 74 68 65 20 53 51 4c 49 54 45 5f 57 49 4e 33   the SQLITE_WIN3
34e0: 32 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41 54  2_MALLOC_VALIDAT
34f0: 45 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e  E macro is defin
3500: 65 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61 73  ed and the.** as
3510: 73 65 72 74 28 29 20 6d 61 63 72 6f 20 69 73 20  sert() macro is 
3520: 65 6e 61 62 6c 65 64 2c 20 65 61 63 68 20 63 61  enabled, each ca
3530: 6c 6c 20 69 6e 74 6f 20 74 68 65 20 57 69 6e 33  ll into the Win3
3540: 32 20 6e 61 74 69 76 65 20 68 65 61 70 20 73 75  2 native heap su
3550: 62 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c 20  bsystem.** will 
3560: 63 61 75 73 65 20 48 65 61 70 56 61 6c 69 64 61  cause HeapValida
3570: 74 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e  te to be called.
3580: 20 20 49 66 20 68 65 61 70 20 76 61 6c 69 64 61    If heap valida
3590: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69 6c  tion should fail
35a0: 2c 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69 6f  , an.** assertio
35b0: 6e 20 77 69 6c 6c 20 62 65 20 74 72 69 67 67 65  n will be trigge
35c0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74  red..**.** (Hist
35d0: 6f 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54 68  orical note:  Th
35e0: 65 72 65 20 75 73 65 64 20 74 6f 20 62 65 20 73  ere used to be s
35f0: 65 76 65 72 61 6c 20 6f 74 68 65 72 20 6f 70 74  everal other opt
3600: 69 6f 6e 73 2c 20 62 75 74 20 77 65 27 76 65 0a  ions, but we've.
3610: 2a 2a 20 70 61 72 65 64 20 69 74 20 64 6f 77 6e  ** pared it down
3620: 20 74 6f 20 6a 75 73 74 20 74 68 65 73 65 20 74   to just these t
3630: 68 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66 20  hree.).**.** If 
3640: 6e 6f 6e 65 20 6f 66 20 74 68 65 20 61 62 6f 76  none of the abov
3650: 65 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74  e are defined, t
3660: 68 65 6e 20 73 65 74 20 53 51 4c 49 54 45 5f 53  hen set SQLITE_S
3670: 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73 0a  YSTEM_MALLOC as.
3680: 2a 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 0a  ** the default..
3690: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53  */.#if defined(S
36a0: 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c  QLITE_SYSTEM_MAL
36b0: 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 53 51 4c  LOC)+defined(SQL
36c0: 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43  ITE_WIN32_MALLOC
36d0: 29 2b 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45  )+defined(SQLITE
36e0: 5f 4d 45 4d 44 45 42 55 47 29 3e 31 0a 23 20 65  _MEMDEBUG)>1.# e
36f0: 72 72 6f 72 20 22 41 74 20 6d 6f 73 74 20 6f 6e  rror "At most on
3700: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
3710: 6e 67 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ng compile-time 
3720: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
3730: 74 69 6f 6e 73 5c 0a 20 69 73 20 61 6c 6c 6f 77  tions\. is allow
3740: 73 3a 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d  s: SQLITE_SYSTEM
3750: 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 45 5f  _MALLOC, SQLITE_
3760: 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51  WIN32_MALLOC, SQ
3770: 4c 49 54 45 5f 4d 45 4d 44 45 42 55 47 22 0a 23  LITE_MEMDEBUG".#
3780: 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69 6e 65  endif.#if define
3790: 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f  d(SQLITE_SYSTEM_
37a0: 4d 41 4c 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28  MALLOC)+defined(
37b0: 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
37c0: 4c 4f 43 29 2b 64 65 66 69 6e 65 64 28 53 51 4c  LOC)+defined(SQL
37d0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d 3d 30  ITE_MEMDEBUG)==0
37e0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
37f0: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 31  _SYSTEM_MALLOC 1
3800: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49  .#endif../*.** I
3810: 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f  f SQLITE_MALLOC_
3820: 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20 6e 6f  SOFT_LIMIT is no
3830: 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 79  t zero, then try
3840: 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a 2a 20   to keep the.** 
3850: 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  sizes of memory 
3860: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65 6c 6f  allocations belo
3870: 77 20 74 68 69 73 20 76 61 6c 75 65 20 77 68 65  w this value whe
3880: 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2f 0a  re possible..*/.
3890: 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c  #if !defined(SQL
38a0: 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f  ITE_MALLOC_SOFT_
38b0: 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e 65 20  LIMIT).# define 
38c0: 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f  SQLITE_MALLOC_SO
38d0: 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a 23 65  FT_LIMIT 1024.#e
38e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65 20 6e  ndif../*.** We n
38f0: 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20 5f 58  eed to define _X
3900: 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73 20 66  OPEN_SOURCE as f
3910: 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65 72 20  ollows in order 
3920: 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72 65 63  to enable.** rec
3930: 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 20 6f  ursive mutexes o
3940: 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79 73 74  n most Unix syst
3950: 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20 4f 53  ems.  But Mac OS
3960: 20 58 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e   X is different.
3970: 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e 5f 53  .** The _XOPEN_S
3980: 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63 61 75  OURCE define cau
3990: 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f 72  ses problems for
39a0: 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61 72 65   Mac OS X we are
39b0: 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69 74 20   told,.** so it 
39c0: 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 72 65  is omitted there
39d0: 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
39e0: 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74 65 72  673..**.** Later
39f0: 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74 20 5f   we learn that _
3a00: 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69 73 20  XOPEN_SOURCE is 
3a10: 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f 72 72  poorly or incorr
3a20: 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ectly.** impleme
3a30: 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73 79 73  nted on some sys
3a40: 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61 76 6f  tems.  So we avo
3a50: 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74 20 61  id defining it a
3a60: 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74 20 69  t all.** if it i
3a70: 73 20 61 6c 72 65 61 64 79 20 64 65 66 69 6e 65  s already define
3a80: 64 20 6f 72 20 69 66 20 69 74 20 69 73 20 75 6e  d or if it is un
3a90: 6e 65 65 64 65 64 20 62 65 63 61 75 73 65 20 77  needed because w
3aa0: 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64 6f 69  e are.** not doi
3ab0: 6e 67 20 61 20 74 68 72 65 61 64 73 61 66 65 20  ng a threadsafe 
3ac0: 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74 20 23  build.  Ticket #
3ad0: 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2681..**.** See 
3ae0: 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32 37 34  also ticket #274
3af0: 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e  1..*/.#if !defin
3b00: 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45  ed(_XOPEN_SOURCE
3b10: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 5f  ) && !defined(__
3b20: 44 41 52 57 49 4e 5f 5f 29 20 26 26 20 21 64 65  DARWIN__) && !de
3b30: 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45 5f 5f 29  fined(__APPLE__)
3b40: 20 26 26 20 53 51 4c 49 54 45 5f 54 48 52 45 41   && SQLITE_THREA
3b50: 44 53 41 46 45 0a 23 20 20 64 65 66 69 6e 65 20  DSAFE.#  define 
3b60: 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 35 30  _XOPEN_SOURCE 50
3b70: 30 20 20 2f 2a 20 4e 65 65 64 65 64 20 74 6f 20  0  /* Needed to 
3b80: 65 6e 61 62 6c 65 20 70 74 68 72 65 61 64 20 72  enable pthread r
3b90: 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73  ecursive mutexes
3ba0: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a   */.#endif../*.*
3bb0: 2a 20 54 68 65 20 54 43 4c 20 68 65 61 64 65 72  * The TCL header
3bc0: 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65 65 64 65  s are only neede
3bd0: 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67  d when compiling
3be0: 20 74 68 65 20 54 43 4c 20 62 69 6e 64 69 6e 67   the TCL binding
3bf0: 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  s..*/.#if define
3c00: 64 28 53 51 4c 49 54 45 5f 54 43 4c 29 20 7c 7c  d(SQLITE_TCL) ||
3c10: 20 64 65 66 69 6e 65 64 28 54 43 4c 53 48 29 0a   defined(TCLSH).
3c20: 23 20 69 6e 63 6c 75 64 65 20 3c 74 63 6c 2e 68  # include <tcl.h
3c30: 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  >.#endif../*.** 
3c40: 4e 44 45 42 55 47 20 61 6e 64 20 53 51 4c 49 54  NDEBUG and SQLIT
3c50: 45 5f 44 45 42 55 47 20 61 72 65 20 6f 70 70 6f  E_DEBUG are oppo
3c60: 73 69 74 65 73 2e 20 20 49 74 20 73 68 6f 75 6c  sites.  It shoul
3c70: 64 20 61 6c 77 61 79 73 20 62 65 20 74 72 75 65  d always be true
3c80: 20 74 68 61 74 0a 2a 2a 20 64 65 66 69 6e 65 64   that.** defined
3c90: 28 4e 44 45 42 55 47 29 3d 3d 21 64 65 66 69 6e  (NDEBUG)==!defin
3ca0: 65 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29  ed(SQLITE_DEBUG)
3cb0: 2e 20 20 49 66 20 74 68 69 73 20 69 73 20 6e 6f  .  If this is no
3cc0: 74 20 63 75 72 72 65 6e 74 6c 79 20 74 72 75 65  t currently true
3cd0: 2c 0a 2a 2a 20 6d 61 6b 65 20 69 74 20 74 72 75  ,.** make it tru
3ce0: 65 20 62 79 20 64 65 66 69 6e 69 6e 67 20 6f 72  e by defining or
3cf0: 20 75 6e 64 65 66 69 6e 69 6e 67 20 4e 44 45 42   undefining NDEB
3d00: 55 47 2e 0a 2a 2a 0a 2a 2a 20 53 65 74 74 69 6e  UG..**.** Settin
3d10: 67 20 4e 44 45 42 55 47 20 6d 61 6b 65 73 20 74  g NDEBUG makes t
3d20: 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c 65 72 20  he code smaller 
3d30: 61 6e 64 20 72 75 6e 20 66 61 73 74 65 72 20 62  and run faster b
3d40: 79 20 64 69 73 61 62 6c 69 6e 67 20 74 68 65 0a  y disabling the.
3d50: 2a 2a 20 6e 75 6d 62 65 72 20 61 73 73 65 72 74  ** number assert
3d60: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
3d70: 20 74 68 65 20 63 6f 64 65 2e 20 20 53 6f 20 77   the code.  So w
3d80: 65 20 77 61 6e 74 20 74 68 65 20 64 65 66 61 75  e want the defau
3d90: 6c 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20  lt action.** to 
3da0: 62 65 20 66 6f 72 20 4e 44 45 42 55 47 20 74 6f  be for NDEBUG to
3db0: 20 62 65 20 73 65 74 20 61 6e 64 20 4e 44 45 42   be set and NDEB
3dc0: 55 47 20 74 6f 20 62 65 20 75 6e 64 65 66 69 6e  UG to be undefin
3dd0: 65 64 20 6f 6e 6c 79 20 69 66 20 53 51 4c 49 54  ed only if SQLIT
3de0: 45 5f 44 45 42 55 47 0a 2a 2a 20 69 73 20 73 65  E_DEBUG.** is se
3df0: 74 2e 20 20 54 68 75 73 20 4e 44 45 42 55 47 20  t.  Thus NDEBUG 
3e00: 62 65 63 6f 6d 65 73 20 61 6e 20 6f 70 74 2d 69  becomes an opt-i
3e10: 6e 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 6e  n rather than an
3e20: 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66 65 61 74   opt-out.** feat
3e30: 75 72 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66  ure..*/.#if !def
3e40: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 26 26 20  ined(NDEBUG) && 
3e50: 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f  !defined(SQLITE_
3e60: 44 45 42 55 47 29 20 0a 23 20 64 65 66 69 6e 65  DEBUG) .# define
3e70: 20 4e 44 45 42 55 47 20 31 0a 23 65 6e 64 69 66   NDEBUG 1.#endif
3e80: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 4e 44 45  .#if defined(NDE
3e90: 42 55 47 29 20 26 26 20 64 65 66 69 6e 65 64 28  BUG) && defined(
3ea0: 53 51 4c 49 54 45 5f 44 45 42 55 47 29 0a 23 20  SQLITE_DEBUG).# 
3eb0: 75 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 65 6e  undef NDEBUG.#en
3ec0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  dif../*.** The t
3ed0: 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20  estcase() macro 
3ee0: 69 73 20 75 73 65 64 20 74 6f 20 61 69 64 20 69  is used to aid i
3ef0: 6e 20 63 6f 76 65 72 61 67 65 20 74 65 73 74 69  n coverage testi
3f00: 6e 67 2e 20 20 57 68 65 6e 20 0a 2a 2a 20 64 6f  ng.  When .** do
3f10: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73  ing coverage tes
3f20: 74 69 6e 67 2c 20 74 68 65 20 63 6f 6e 64 69 74  ting, the condit
3f30: 69 6f 6e 20 69 6e 73 69 64 65 20 74 68 65 20 61  ion inside the a
3f40: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 65  rgument to.** te
3f50: 73 74 63 61 73 65 28 29 20 6d 75 73 74 20 62 65  stcase() must be
3f60: 20 65 76 61 6c 75 61 74 65 64 20 62 6f 74 68 20   evaluated both 
3f70: 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 20 69  true and false i
3f80: 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 67 65  n order to.** ge
3f90: 74 20 66 75 6c 6c 20 62 72 61 6e 63 68 20 63 6f  t full branch co
3fa0: 76 65 72 61 67 65 2e 20 20 54 68 65 20 74 65 73  verage.  The tes
3fb0: 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20 69 73  tcase() macro is
3fc0: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 74 6f 20   inserted.** to 
3fd0: 68 65 6c 70 20 65 6e 73 75 72 65 20 61 64 65 71  help ensure adeq
3fe0: 75 61 74 65 20 74 65 73 74 20 63 6f 76 65 72 61  uate test covera
3ff0: 67 65 20 69 6e 20 70 6c 61 63 65 73 20 77 68 65  ge in places whe
4000: 72 65 20 73 69 6d 70 6c 65 0a 2a 2a 20 63 6f 6e  re simple.** con
4010: 64 69 74 69 6f 6e 2f 64 65 63 69 73 69 6f 6e 20  dition/decision 
4020: 63 6f 76 65 72 61 67 65 20 69 73 20 69 6e 61 64  coverage is inad
4030: 65 71 75 61 74 65 2e 20 20 46 6f 72 20 65 78 61  equate.  For exa
4040: 6d 70 6c 65 2c 20 74 65 73 74 63 61 73 65 28 29  mple, testcase()
4050: 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
4060: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 62 6f 75  to make sure bou
4070: 6e 64 61 72 79 20 76 61 6c 75 65 73 20 61 72 65  ndary values are
4080: 20 74 65 73 74 65 64 2e 20 20 46 6f 72 0a 2a 2a   tested.  For.**
4090: 20 62 69 74 6d 61 73 6b 20 74 65 73 74 73 2c 20   bitmask tests, 
40a0: 74 65 73 74 63 61 73 65 28 29 20 63 61 6e 20 62  testcase() can b
40b0: 65 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73  e used to make s
40c0: 75 72 65 20 65 61 63 68 20 62 69 74 0a 2a 2a 20  ure each bit.** 
40d0: 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 61  is significant a
40e0: 6e 64 20 75 73 65 64 20 61 74 20 6c 65 61 73 74  nd used at least
40f0: 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 77 69 74 63   once.  On switc
4100: 68 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  h statements.** 
4110: 77 68 65 72 65 20 6d 75 6c 74 69 70 6c 65 20 63  where multiple c
4120: 61 73 65 73 20 67 6f 20 74 6f 20 74 68 65 20 73  ases go to the s
4130: 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20 63 6f 64  ame block of cod
4140: 65 2c 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a  e, testcase().**
4150: 20 63 61 6e 20 69 6e 73 75 72 65 20 74 68 61 74   can insure that
4160: 20 61 6c 6c 20 63 61 73 65 73 20 61 72 65 20 65   all cases are e
4170: 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2f 0a  valuated..**.*/.
4180: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 43 4f  #ifdef SQLITE_CO
4190: 56 45 52 41 47 45 5f 54 45 53 54 0a 53 51 4c 49  VERAGE_TEST.SQLI
41a0: 54 45 5f 50 52 49 56 41 54 45 20 20 20 76 6f 69  TE_PRIVATE   voi
41b0: 64 20 73 71 6c 69 74 65 33 43 6f 76 65 72 61 67  d sqlite3Coverag
41c0: 65 28 69 6e 74 29 3b 0a 23 20 64 65 66 69 6e 65  e(int);.# define
41d0: 20 74 65 73 74 63 61 73 65 28 58 29 20 20 69 66   testcase(X)  if
41e0: 28 20 58 20 29 7b 20 73 71 6c 69 74 65 33 43 6f  ( X ){ sqlite3Co
41f0: 76 65 72 61 67 65 28 5f 5f 4c 49 4e 45 5f 5f 29  verage(__LINE__)
4200: 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  ; }.#else.# defi
4210: 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 0a 23  ne testcase(X).#
4220: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
4230: 20 54 45 53 54 4f 4e 4c 59 20 6d 61 63 72 6f 20   TESTONLY macro 
4240: 69 73 20 75 73 65 64 20 74 6f 20 65 6e 63 6c 6f  is used to enclo
4250: 73 65 20 76 61 72 69 61 62 6c 65 20 64 65 63 6c  se variable decl
4260: 61 72 61 74 69 6f 6e 73 20 6f 72 0a 2a 2a 20 6f  arations or.** o
4270: 74 68 65 72 20 62 69 74 73 20 6f 66 20 63 6f 64  ther bits of cod
4280: 65 20 74 68 61 74 20 61 72 65 20 6e 65 65 64 65  e that are neede
4290: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 74 68 65  d to support the
42a0: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 77 69   arguments.** wi
42b0: 74 68 69 6e 20 74 65 73 74 63 61 73 65 28 29 20  thin testcase() 
42c0: 61 6e 64 20 61 73 73 65 72 74 28 29 20 6d 61 63  and assert() mac
42d0: 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66  ros..*/.#if !def
42e0: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 7c 7c 20  ined(NDEBUG) || 
42f0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 43  defined(SQLITE_C
4300: 4f 56 45 52 41 47 45 5f 54 45 53 54 29 0a 23 20  OVERAGE_TEST).# 
4310: 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28  define TESTONLY(
4320: 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65  X)  X.#else.# de
4330: 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28 58 29  fine TESTONLY(X)
4340: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 53  .#endif../*.** S
4350: 6f 6d 65 74 69 6d 65 73 20 77 65 20 6e 65 65 64  ometimes we need
4360: 20 61 20 73 6d 61 6c 6c 20 61 6d 6f 75 6e 74 20   a small amount 
4370: 6f 66 20 63 6f 64 65 20 73 75 63 68 20 61 73 20  of code such as 
4380: 61 20 76 61 72 69 61 62 6c 65 20 69 6e 69 74 69  a variable initi
4390: 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  alization.** to 
43a0: 73 65 74 75 70 20 66 6f 72 20 61 20 6c 61 74 65  setup for a late
43b0: 72 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  r assert() state
43c0: 6d 65 6e 74 2e 20 20 57 65 20 64 6f 20 6e 6f 74  ment.  We do not
43d0: 20 77 61 6e 74 20 74 68 69 73 20 63 6f 64 65 20   want this code 
43e0: 74 6f 0a 2a 2a 20 61 70 70 65 61 72 20 77 68 65  to.** appear whe
43f0: 6e 20 61 73 73 65 72 74 28 29 20 69 73 20 64 69  n assert() is di
4400: 73 61 62 6c 65 64 2e 20 20 54 68 65 20 66 6f 6c  sabled.  The fol
4410: 6c 6f 77 69 6e 67 20 6d 61 63 72 6f 20 69 73 20  lowing macro is 
4420: 74 68 65 72 65 66 6f 72 65 0a 2a 2a 20 75 73 65  therefore.** use
4430: 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 61  d to contain tha
4440: 74 20 73 65 74 75 70 20 63 6f 64 65 2e 20 20 54  t setup code.  T
4450: 68 65 20 22 56 56 41 22 20 61 63 72 6f 6e 79 6d  he "VVA" acronym
4460: 20 73 74 61 6e 64 73 20 66 6f 72 0a 2a 2a 20 22   stands for.** "
4470: 56 65 72 69 66 69 63 61 74 69 6f 6e 2c 20 56 61  Verification, Va
4480: 6c 69 64 61 74 69 6f 6e 2c 20 61 6e 64 20 41 63  lidation, and Ac
4490: 63 72 65 64 69 74 61 74 69 6f 6e 22 2e 20 20 49  creditation".  I
44a0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
44b0: 68 65 0a 2a 2a 20 63 6f 64 65 20 77 69 74 68 69  he.** code withi
44c0: 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 20 77 69 6c  n VVA_ONLY() wil
44d0: 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 75 72 69 6e  l only run durin
44e0: 67 20 76 65 72 69 66 69 63 61 74 69 6f 6e 20 70  g verification p
44f0: 72 6f 63 65 73 73 65 73 2e 0a 2a 2f 0a 23 69 66  rocesses..*/.#if
4500: 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 20 64 65  ndef NDEBUG.# de
4510: 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29  fine VVA_ONLY(X)
4520: 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65 66 69    X.#else.# defi
4530: 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29 0a 23  ne VVA_ONLY(X).#
4540: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
4550: 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45   ALWAYS and NEVE
4560: 52 20 6d 61 63 72 6f 73 20 73 75 72 72 6f 75 6e  R macros surroun
4570: 64 20 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73  d boolean expres
4580: 73 69 6f 6e 73 20 77 68 69 63 68 20 0a 2a 2a 20  sions which .** 
4590: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
45a0: 61 6c 77 61 79 73 20 62 65 20 74 72 75 65 20 6f  always be true o
45b0: 72 20 66 61 6c 73 65 2c 20 72 65 73 70 65 63 74  r false, respect
45c0: 69 76 65 6c 79 2e 20 20 53 75 63 68 0a 2a 2a 20  ively.  Such.** 
45d0: 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 75 6c  expressions coul
45e0: 64 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f  d be omitted fro
45f0: 6d 20 74 68 65 20 63 6f 64 65 20 63 6f 6d 70 6c  m the code compl
4600: 65 74 65 6c 79 2e 20 20 42 75 74 20 74 68 65 79  etely.  But they
4610: 0a 2a 2a 20 61 72 65 20 69 6e 63 6c 75 64 65 64  .** are included
4620: 20 69 6e 20 61 20 66 65 77 20 63 61 73 65 73 20   in a few cases 
4630: 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 68 61  in order to enha
4640: 6e 63 65 20 74 68 65 20 72 65 73 69 6c 69 65 6e  nce the resilien
4650: 63 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  ce.** of SQLite 
4660: 74 6f 20 75 6e 65 78 70 65 63 74 65 64 20 62 65  to unexpected be
4670: 68 61 76 69 6f 72 20 2d 20 74 6f 20 6d 61 6b 65  havior - to make
4680: 20 74 68 65 20 63 6f 64 65 20 22 73 65 6c 66 2d   the code "self-
4690: 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 6f 72 20 22  healing".** or "
46a0: 64 75 63 74 69 6c 65 22 20 72 61 74 68 65 72 20  ductile" rather 
46b0: 74 68 61 6e 20 62 65 69 6e 67 20 22 62 72 69 74  than being "brit
46c0: 74 6c 65 22 20 61 6e 64 20 63 72 61 73 68 69 6e  tle" and crashin
46d0: 67 20 61 74 20 74 68 65 20 66 69 72 73 74 0a 2a  g at the first.*
46e0: 2a 20 68 69 6e 74 20 6f 66 20 75 6e 70 6c 61 6e  * hint of unplan
46f0: 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
4700: 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
4710: 64 73 2c 20 41 4c 57 41 59 53 20 61 6e 64 20 4e  ds, ALWAYS and N
4720: 45 56 45 52 20 61 72 65 20 61 64 64 65 64 20 66  EVER are added f
4730: 6f 72 20 64 65 66 65 6e 73 69 76 65 20 63 6f 64  or defensive cod
4740: 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 64 6f  e..**.** When do
4750: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73  ing coverage tes
4760: 74 69 6e 67 20 41 4c 57 41 59 53 20 61 6e 64 20  ting ALWAYS and 
4770: 4e 45 56 45 52 20 61 72 65 20 68 61 72 64 2d 63  NEVER are hard-c
4780: 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 65 20 74 72  oded to.** be tr
4790: 75 65 20 61 6e 64 20 66 61 6c 73 65 20 73 6f 20  ue and false so 
47a0: 74 68 61 74 20 74 68 65 20 75 6e 72 65 61 63 68  that the unreach
47b0: 61 62 6c 65 20 63 6f 64 65 20 74 68 65 6e 20 73  able code then s
47c0: 70 65 63 69 66 79 20 77 69 6c 6c 0a 2a 2a 20 6e  pecify will.** n
47d0: 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 61 73  ot be counted as
47e0: 20 75 6e 74 65 73 74 65 64 20 63 6f 64 65 2e 0a   untested code..
47f0: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53  */.#if defined(S
4800: 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54  QLITE_COVERAGE_T
4810: 45 53 54 29 0a 23 20 64 65 66 69 6e 65 20 41 4c  EST).# define AL
4820: 57 41 59 53 28 58 29 20 20 20 20 20 20 28 31 29  WAYS(X)      (1)
4830: 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 28  .# define NEVER(
4840: 58 29 20 20 20 20 20 20 20 28 30 29 0a 23 65 6c  X)       (0).#el
4850: 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42  if !defined(NDEB
4860: 55 47 29 0a 23 20 64 65 66 69 6e 65 20 41 4c 57  UG).# define ALW
4870: 41 59 53 28 58 29 20 20 20 20 20 20 28 28 58 29  AYS(X)      ((X)
4880: 3f 31 3a 28 61 73 73 65 72 74 28 30 29 2c 30 29  ?1:(assert(0),0)
4890: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52  ).# define NEVER
48a0: 28 58 29 20 20 20 20 20 20 20 28 28 58 29 3f 28  (X)       ((X)?(
48b0: 61 73 73 65 72 74 28 30 29 2c 31 29 3a 30 29 0a  assert(0),1):0).
48c0: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 41  #else.# define A
48d0: 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28 58  LWAYS(X)      (X
48e0: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52  ).# define NEVER
48f0: 28 58 29 20 20 20 20 20 20 20 28 58 29 0a 23 65  (X)       (X).#e
4900: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75  ndif../*.** Retu
4910: 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  rn true (non-zer
4920: 6f 29 20 69 66 20 74 68 65 20 69 6e 70 75 74 20  o) if the input 
4930: 69 73 20 61 20 69 6e 74 65 67 65 72 20 74 68 61  is a integer tha
4940: 74 20 69 73 20 74 6f 6f 20 6c 61 72 67 65 0a 2a  t is too large.*
4950: 2a 20 74 6f 20 66 69 74 20 69 6e 20 33 32 2d 62  * to fit in 32-b
4960: 69 74 73 2e 20 20 54 68 69 73 20 6d 61 63 72 6f  its.  This macro
4970: 20 69 73 20 75 73 65 64 20 69 6e 73 69 64 65 20   is used inside 
4980: 6f 66 20 76 61 72 69 6f 75 73 20 74 65 73 74 63  of various testc
4990: 61 73 65 28 29 0a 2a 2a 20 6d 61 63 72 6f 73 20  ase().** macros 
49a0: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 77  to verify that w
49b0: 65 20 68 61 76 65 20 74 65 73 74 65 64 20 53 51  e have tested SQ
49c0: 4c 69 74 65 20 66 6f 72 20 6c 61 72 67 65 2d 66  Lite for large-f
49d0: 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a  ile support..*/.
49e0: 23 64 65 66 69 6e 65 20 49 53 5f 42 49 47 5f 49  #define IS_BIG_I
49f0: 4e 54 28 58 29 20 20 28 28 28 58 29 26 7e 28 69  NT(X)  (((X)&~(i
4a00: 36 34 29 30 78 66 66 66 66 66 66 66 66 29 21 3d  64)0xffffffff)!=
4a10: 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61  0)../*.** The ma
4a20: 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 28 29 20 69  cro unlikely() i
4a30: 73 20 61 20 68 69 6e 74 20 74 68 61 74 20 73 75  s a hint that su
4a40: 72 72 6f 75 6e 64 73 20 61 20 62 6f 6f 6c 65 61  rrounds a boolea
4a50: 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
4a60: 74 68 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20  that is usually 
4a70: 66 61 6c 73 65 2e 20 20 4d 61 63 72 6f 20 6c 69  false.  Macro li
4a80: 6b 65 6c 79 28 29 20 73 75 72 72 6f 75 6e 64 73  kely() surrounds
4a90: 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 65 78  .** a boolean ex
4aa0: 70 72 65 73 73 69 6f 6e 20 74 68 61 74 20 69 73  pression that is
4ab0: 20 75 73 75 61 6c 6c 79 20 74 72 75 65 2e 20 20   usually true.  
4ac0: 47 43 43 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  GCC is able to.*
4ad0: 2a 20 75 73 65 20 74 68 65 73 65 20 68 69 6e 74  * use these hint
4ae0: 73 20 74 6f 20 67 65 6e 65 72 61 74 65 20 62 65  s to generate be
4af0: 74 74 65 72 20 63 6f 64 65 2c 20 73 6f 6d 65 74  tter code, somet
4b00: 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66  imes..*/.#if def
4b10: 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26  ined(__GNUC__) &
4b20: 26 20 30 0a 23 20 64 65 66 69 6e 65 20 6c 69 6b  & 0.# define lik
4b30: 65 6c 79 28 58 29 20 20 20 20 5f 5f 62 75 69 6c  ely(X)    __buil
4b40: 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 31  tin_expect((X),1
4b50: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b  ).# define unlik
4b60: 65 6c 79 28 58 29 20 20 5f 5f 62 75 69 6c 74 69  ely(X)  __builti
4b70: 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 30 29 0a  n_expect((X),0).
4b80: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 6c  #else.# define l
4b90: 69 6b 65 6c 79 28 58 29 20 20 20 20 21 21 28 58  ikely(X)    !!(X
4ba0: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b  ).# define unlik
4bb0: 65 6c 79 28 58 29 20 20 21 21 28 58 29 0a 23 65  ely(X)  !!(X).#e
4bc0: 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  ndif../*********
4bd0: 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71  ***** Include sq
4be0: 6c 69 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d  lite3.h in the m
4bf0: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49  iddle of sqliteI
4c00: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
4c10: 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****/./*********
4c20: 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65  ***** Begin file
4c30: 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a   sqlite3.h *****
4c40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4c50: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4c60: 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31  ****/./*.** 2001
4c70: 20 53 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a   September 15.**
4c80: 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64  .** The author d
4c90: 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67  isclaims copyrig
4ca0: 68 74 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63  ht to this sourc
4cb0: 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63  e code.  In plac
4cc0: 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20  e of.** a legal 
4cd0: 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 69 73 20  notice, here is 
4ce0: 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a  a blessing:.**.*
4cf0: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20  *    May you do 
4d00: 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69  good and not evi
4d10: 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  l..**    May you
4d20: 20 66 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73   find forgivenes
4d30: 73 20 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61  s for yourself a
4d40: 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72  nd forgive other
4d50: 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  s..**    May you
4d60: 20 73 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e   share freely, n
4d70: 65 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65  ever taking more
4d80: 20 74 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a   than you give..
4d90: 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **.*************
4da0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4db0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4dc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4dd0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20  ************.** 
4de0: 54 68 69 73 20 68 65 61 64 65 72 20 66 69 6c 65  This header file
4df0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
4e00: 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20  erface that the 
4e10: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a  SQLite library.*
4e20: 2a 20 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c  * presents to cl
4e30: 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20  ient programs.  
4e40: 49 66 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c  If a C-function,
4e50: 20 73 74 72 75 63 74 75 72 65 2c 20 64 61 74 61   structure, data
4e60: 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73  type,.** or cons
4e70: 74 61 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20  tant definition 
4e80: 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
4e90: 69 6e 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68  in this file, th
4ea0: 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  en it is.** not 
4eb0: 61 20 70 75 62 6c 69 73 68 65 64 20 41 50 49 20  a published API 
4ec0: 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75  of SQLite, is su
4ed0: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
4ee0: 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63  without.** notic
4ef0: 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  e, and should no
4f00: 74 20 62 65 20 72 65 66 65 72 65 6e 63 65 64 20  t be referenced 
4f10: 62 79 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74  by programs that
4f20: 20 75 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a   use SQLite..**.
4f30: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64  ** Some of the d
4f40: 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20  efinitions that 
4f50: 61 72 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65  are in this file
4f60: 20 61 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a   are marked as.*
4f70: 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22  * "experimental"
4f80: 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20  .  Experimental 
4f90: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
4fa0: 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66  ormally new.** f
4fb0: 65 61 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79  eatures recently
4fc0: 20 61 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65   added to SQLite
4fd0: 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74  .  We do not ant
4fe0: 69 63 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a  icipate changes.
4ff0: 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74  ** to experiment
5000: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 62 75  al interfaces bu
5010: 74 20 72 65 73 65 72 76 65 20 74 68 65 20 72 69  t reserve the ri
5020: 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  ght to make mino
5030: 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20  r changes.** if 
5040: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
5050: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
5060: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
5070: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
5080: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
5090: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
50a0: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
50b0: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
50c0: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
50d0: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
50e0: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
50f0: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
5100: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
5110: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
5120: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
5130: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
5140: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
5150: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
5160: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
5170: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
5180: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
5190: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
51a0: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
51b0: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
51c0: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
51d0: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
51e0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
51f0: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
5200: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
5210: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
5220: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
5230: 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  cess..*/.#ifndef
5240: 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65   _SQLITE3_H_.#de
5250: 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f  fine _SQLITE3_H_
5260: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
5270: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
5280: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
5290: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
52a0: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
52b0: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
52c0: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
52d0: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65   C++..*/.#if 0.e
52e0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
52f0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  if.../*.** Add t
5300: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
5310: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a  erride 'extern'.
5320: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
5330: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
5340: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
5350: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23  extern.#endif..#
5360: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50  ifndef SQLITE_AP
5370: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
5380: 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f  E_API.#endif.../
5390: 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70  *.** These no-op
53a0: 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64   macros are used
53b0: 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74   in front of int
53c0: 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20  erfaces to mark 
53d0: 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  those.** interfa
53e0: 63 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65  ces as either de
53f0: 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65  precated or expe
5400: 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61  rimental.  New a
5410: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
5420: 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65  hould not use de
5430: 70 72 65 63 61 74 65 64 20 69 6e 74 65 72 66 61  precated interfa
5440: 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 73  ces - they are s
5450: 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77  upport for backw
5460: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
5470: 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70  ility only.  App
5480: 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73  lication writers
5490: 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65   should be aware
54a0: 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d   that.** experim
54b0: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
54c0: 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20   are subject to 
54d0: 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20  change in point 
54e0: 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
54f0: 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65  These macros use
5500: 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20  d to resolve to 
5510: 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66  various kinds of
5520: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
5530: 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65  that.** would ge
5540: 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d  nerate warning m
5550: 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65  essages when the
5560: 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75  y were used.  Bu
5570: 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c  t that.** compil
5580: 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75  er magic ended u
5590: 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63  p generating suc
55a0: 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75  h a flurry of bu
55b0: 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61  g reports.** tha
55c0: 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20  t we have taken 
55d0: 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67  it all out and g
55e0: 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e  one back to usin
55f0: 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70  g simple.** noop
5600: 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66   macros..*/.#def
5610: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45  ine SQLITE_DEPRE
5620: 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51  CATED.#define SQ
5630: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
5640: 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20  L../*.** Ensure 
5650: 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65  these symbols we
5660: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
5670: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
5680: 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a  header file..*/.
5690: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
56a0: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51  RSION.# undef SQ
56b0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e  LITE_VERSION.#en
56c0: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54  dif.#ifdef SQLIT
56d0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
56e0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
56f0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
5700: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
5710: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
5720: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
5730: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a  ion Numbers.**.*
5740: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f  * ^(The [SQLITE_
5750: 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72  VERSION] C prepr
5760: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e  ocessor macro in
5770: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68   the sqlite3.h h
5780: 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74  eader.** evaluat
5790: 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c  es to a string l
57a0: 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74  iteral that is t
57b0: 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  he SQLite versio
57c0: 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  n in the.** form
57d0: 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65  at "X.Y.Z" where
57e0: 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20   X is the major 
57f0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
5800: 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20  always 3 for.** 
5810: 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69  SQLite3) and Y i
5820: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73  s the minor vers
5830: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a  ion number and Z
5840: 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20   is the release 
5850: 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54  number.)^.** ^(T
5860: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
5870: 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65  ON_NUMBER] C pre
5880: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
5890: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69  resolves to an i
58a0: 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74  nteger.** with t
58b0: 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30  he value (X*1000
58c0: 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a  000 + Y*1000 + Z
58d0: 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e  ) where X, Y, an
58e0: 64 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65  d Z are the same
58f0: 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64  .** numbers used
5900: 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   in [SQLITE_VERS
5910: 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53  ION].)^.** The S
5920: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
5930: 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76  MBER for any giv
5940: 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  en release of SQ
5950: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a  Lite will also.*
5960: 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  * be larger than
5970: 20 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f   the release fro
5980: 6d 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65  m which it is de
5990: 72 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59  rived.  Either Y
59a0: 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64   will.** be held
59b0: 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20   constant and Z 
59c0: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e  will be incremen
59d0: 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69  ted or else Y wi
59e0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
59f0: 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20  d.** and Z will 
5a00: 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f  be reset to zero
5a10: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65  ..**.** Since ve
5a20: 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51  rsion 3.6.18, SQ
5a30: 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65  Lite source code
5a40: 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64   has been stored
5a50: 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72   in the.** <a hr
5a60: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66  ef="http://www.f
5a70: 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e  ossil-scm.org/">
5a80: 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61  Fossil configura
5a90: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a  tion management.
5aa0: 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20  ** system</a>.  
5ab0: 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  ^The SQLITE_SOUR
5ac0: 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c  CE_ID macro eval
5ad0: 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74  uates to.** a st
5ae0: 72 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74  ring which ident
5af0: 69 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c  ifies a particul
5b00: 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53  ar check-in of S
5b10: 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20  QLite.** within 
5b20: 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  its configuratio
5b30: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73  n management sys
5b40: 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  tem.  ^The SQLIT
5b50: 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73  E_SOURCE_ID.** s
5b60: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74  tring contains t
5b70: 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  he date and time
5b80: 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e   of the check-in
5b90: 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48   (UTC) and an SH
5ba0: 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68  A1.** hash of th
5bb0: 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20  e entire source 
5bc0: 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tree..**.** See 
5bd0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c  also: [sqlite3_l
5be0: 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a  ibversion()],.**
5bf0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
5c00: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20  sion_number()], 
5c10: 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  [sqlite3_sourcei
5c20: 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
5c30: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
5c40: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
5c50: 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  d()]..*/.#define
5c60: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20   SQLITE_VERSION 
5c70: 20 20 20 20 20 20 20 22 33 2e 37 2e 31 33 22 0a         "3.7.13".
5c80: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
5c90: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30  ERSION_NUMBER 30
5ca0: 30 37 30 31 33 0a 23 64 65 66 69 6e 65 20 53 51  07013.#define SQ
5cb0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
5cc0: 20 20 20 20 22 32 30 31 32 2d 30 36 2d 30 37 20      "2012-06-07 
5cd0: 30 37 3a 32 34 3a 30 34 20 35 30 36 30 30 38 66  07:24:04 506008f
5ce0: 30 30 30 62 61 34 61 66 30 62 33 35 64 61 30 32  000ba4af0b35da02
5cf0: 33 62 38 63 35 32 66 37 61 33 66 35 30 33 33 62  3b8c52f7a3f5033b
5d00: 64 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  d"../*.** CAPI3R
5d10: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
5d20: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
5d30: 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  bers.** KEYWORDS
5d40: 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  : sqlite3_versio
5d50: 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  n, sqlite3_sourc
5d60: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
5d70: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
5d80: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
5d90: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
5da0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
5db0: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
5dc0: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
5dd0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
5de0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
5df0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
5e00: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
5e10: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
5e20: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
5e30: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
5e40: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
5e50: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
5e60: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
5e70: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
5e80: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
5e90: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
5ea0: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
5eb0: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
5ec0: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
5ed0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
5ee0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
5ef0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
5f00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
5f10: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
5f20: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
5f30: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
5f40: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
5f50: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
5f60: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
5f70: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
5f80: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
5f90: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
5fa0: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
5fb0: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
5fc0: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
5fd0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
5fe0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
5ff0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
6000: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
6010: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
6020: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
6030: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
6040: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
6050: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
6060: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
6070: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
6080: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
6090: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
60a0: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
60b0: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
60c0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
60d0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
60e0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
60f0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
6100: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
6110: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
6120: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
6130: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
6140: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
6150: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
6160: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
6170: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
6180: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
6190: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
61a0: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
61b0: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
61c0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
61d0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
61e0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
61f0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
6200: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
6210: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
6220: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
6230: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
6240: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
6250: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
6260: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
6270: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
6280: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
6290: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
62a0: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
62b0: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
62c0: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
62d0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
62e0: 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76  t char sqlite3_v
62f0: 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54  ersion[] = SQLIT
6300: 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54  E_VERSION;.SQLIT
6310: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
6320: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
6330: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  sion(void);.SQLI
6340: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
6350: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
6360: 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  eid(void);.SQLIT
6370: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
6380: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
6390: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ber(void);../*.*
63a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
63b0: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d  Time Library Com
63c0: 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  pilation Options
63d0: 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a   Diagnostics.**.
63e0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
63f0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
6400: 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  ed() function re
6410: 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a  turns 0 or 1 .**
6420: 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74   indicating whet
6430: 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65  her the specifie
6440: 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66  d option was def
6450: 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70  ined at .** comp
6460: 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  ile time.  ^The 
6470: 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d  SQLITE_ prefix m
6480: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72  ay be omitted fr
6490: 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f  om the .** optio
64a0: 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f  n name passed to
64b0: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
64c0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20  option_used().  
64d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
64e0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
64f0: 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  n_get() function
6500: 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e   allows iteratin
6510: 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69  g.** over the li
6520: 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68  st of options th
6530: 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20  at were defined 
6540: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20  at compile time 
6550: 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20  by.** returning 
6560: 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65  the N-th compile
6570: 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72   time option str
6580: 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f  ing.  ^If N is o
6590: 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20  ut of range,.** 
65a0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
65b0: 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75  ption_get() retu
65c0: 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
65d0: 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  er.  ^The SQLITE
65e0: 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20  _ .** prefix is 
65f0: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79  omitted from any
6600: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
6610: 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
6620: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6630: 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70  et()..**.** ^Sup
6640: 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61  port for the dia
6650: 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  gnostic function
6660: 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  s sqlite3_compil
6670: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a  eoption_used().*
6680: 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
6690: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
66a0: 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  ) may be omitted
66b0: 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74   by specifying t
66c0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
66d0: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f  MIT_COMPILEOPTIO
66e0: 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20  N_DIAGS] option 
66f0: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
6700: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
6710: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b   SQL functions [
6720: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
6730: 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64  tion_used()] and
6740: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  .** [sqlite_comp
6750: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d  ileoption_get()]
6760: 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c   and the [compil
6770: 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61  e_options pragma
6780: 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  ]..*/.#ifndef SQ
6790: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
67a0: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51  EOPTION_DIAGS.SQ
67b0: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
67c0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
67d0: 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68  on_used(const ch
67e0: 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53  ar *zOptName);.S
67f0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
6800: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
6810: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
6820: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
6830: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6840: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
6850: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
6860: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
6870: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
6880: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
6890: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
68a0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
68b0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
68c0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
68d0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
68e0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
68f0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
6900: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
6910: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
6920: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
6930: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
6940: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
6950: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
6960: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
6970: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
6980: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
6990: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
69a0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
69b0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
69c0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
69d0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
69e0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
69f0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
6a00: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
6a10: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
6a20: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
6a30: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
6a40: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
6a50: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
6a60: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
6a70: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
6a80: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
6a90: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
6aa0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
6ab0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
6ac0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
6ad0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
6ae0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
6af0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
6b00: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
6b10: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
6b20: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
6b30: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
6b40: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
6b50: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
6b60: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
6b70: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
6b80: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
6b90: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
6ba0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
6bb0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
6bc0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
6bd0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
6be0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
6bf0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
6c00: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
6c10: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
6c20: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
6c30: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
6c40: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
6c50: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
6c60: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
6c70: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
6c80: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
6c90: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
6ca0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
6cb0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
6cc0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
6cd0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
6ce0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
6cf0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
6d00: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
6d10: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
6d20: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
6d30: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
6d40: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
6d50: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
6d60: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
6d70: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
6d80: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
6d90: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
6da0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
6db0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
6dc0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
6dd0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
6de0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
6df0: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
6e00: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
6e10: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
6e20: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
6e30: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
6e40: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
6e50: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
6e60: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
6e70: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
6e80: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
6e90: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
6ea0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
6eb0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
6ec0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
6ed0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
6ee0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
6ef0: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
6f00: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
6f10: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
6f20: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
6f30: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
6f40: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
6f50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
6f60: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
6f70: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
6f80: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
6f90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
6fa0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
6fb0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
6fc0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
6fd0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
6fe0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
6ff0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
7000: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
7010: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
7020: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
7030: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
7040: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
7050: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
7060: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
7070: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
7080: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
7090: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
70a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
70b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
70c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
70d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
70e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
70f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
7100: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
7110: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
7120: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
7130: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
7140: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
7150: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
7160: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
7170: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
7180: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
7190: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
71a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
71b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
71c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
71d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
71e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
71f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
7200: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
7210: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
7220: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
7230: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
7240: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
7250: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
7260: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
7270: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
7280: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
7290: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
72a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
72b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
72c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
72d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
72e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
72f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
7300: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
7310: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
7320: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
7330: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
7340: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
7350: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
7360: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
7370: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
7380: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
7390: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
73a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
73b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
73c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
73d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
73e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
73f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
7400: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
7410: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
7420: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
7430: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
7440: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
7450: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
7460: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
7470: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
7480: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
7490: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
74a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
74b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
74c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
74d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
74e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
74f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
7500: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
7510: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
7520: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
7530: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
7540: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
7550: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
7560: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
7570: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
7580: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
7590: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
75a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
75b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
75c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
75d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
75e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
75f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
7600: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
7610: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
7620: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
7630: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
7640: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
7650: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
7660: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
7670: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
7680: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
7690: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
76a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
76b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
76c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
76d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
76e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
76f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
7700: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
7710: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
7720: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
7730: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
7740: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
7750: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
7760: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
7770: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
7780: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
7790: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
77a0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
77b0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
77c0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
77d0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
77e0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
77f0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
7800: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
7810: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
7820: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
7830: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
7840: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
7850: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
7860: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
7870: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
7880: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
7890: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
78a0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
78b0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
78c0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
78d0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
78e0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
78f0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
7900: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
7910: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
7920: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
7930: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
7940: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
7950: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
7960: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
7970: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
7980: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
7990: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
79a0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
79b0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
79c0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
79d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
79e0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
79f0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
7a00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
7a10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
7a20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
7a30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
7a40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
7a50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
7a60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
7a70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
7a80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
7a90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
7aa0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
7ab0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
7ac0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
7ad0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
7ae0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
7af0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
7b00: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
7b10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c  qlite3_close(sql
7b20: 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ite3 *);../*.** 
7b30: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
7b40: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
7b50: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
7b60: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
7b70: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
7b80: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
7b90: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
7ba0: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
7bb0: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
7bc0: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
7bd0: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
7be0: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
7bf0: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
7c00: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
7c10: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
7c20: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a  on Interface.**.
7c30: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
7c40: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
7c50: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
7c60: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
7c70: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
7c80: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
7c90: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
7ca0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
7cb0: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
7cc0: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
7cd0: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
7ce0: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
7cf0: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
7d00: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
7d10: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
7d20: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
7d30: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
7d40: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
7d50: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
7d60: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
7d70: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
7d80: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
7d90: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
7da0: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
7db0: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
7dc0: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
7dd0: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
7de0: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
7df0: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
7e00: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
7e10: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
7e20: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
7e30: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
7e40: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
7e50: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
7e60: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
7e70: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
7e80: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
7e90: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
7ea0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
7eb0: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
7ec0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c  e3_exec() is rel
7ed0: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ayed through to 
7ee0: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74  the 1st argument
7ef0: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c   of each.** call
7f00: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  back invocation.
7f10: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
7f20: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  ck pointer to sq
7f30: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
7f40: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f  is NULL, then no
7f50: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65   callback is eve
7f60: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65  r invoked and re
7f70: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a  sult rows are.**
7f80: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
7f90: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
7fa0: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61  urs while evalua
7fb0: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61  ting the SQL sta
7fc0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
7fd0: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  nto.** sqlite3_e
7fe0: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63  xec(), then exec
7ff0: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
8000: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73  rent statement s
8010: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73  tops and.** subs
8020: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  equent statement
8030: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20  s are skipped.  
8040: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
8050: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
8060: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f  _exec().** is no
8070: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20  t NULL then any 
8080: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73  error message is
8090: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
80a0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
80b0: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
80c0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73  alloc()] and pas
80d0: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
80e0: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
80f0: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  er..** To avoid 
8100: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68  memory leaks, th
8110: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
8120: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  ould invoke [sql
8130: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
8140: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  on error message
8150: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
8160: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
8170: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a  h parameter of.*
8180: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  * of sqlite3_exe
8190: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
81a0: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
81b0: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
81c0: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
81d0: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
81e0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
81f0: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
8200: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
8210: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
8220: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
8230: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
8240: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
8250: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
8260: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
8270: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
8280: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
8290: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
82a0: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
82b0: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
82c0: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
82d0: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
82e0: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
82f0: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
8300: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
8310: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
8320: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
8330: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
8340: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
8350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8360: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
8370: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
8380: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
8390: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
83a0: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
83b0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
83c0: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
83d0: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
83e0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
83f0: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
8400: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
8410: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
8420: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
8430: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
8440: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
8450: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
8460: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
8470: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
8480: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
8490: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
84a0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
84b0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
84c0: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
84d0: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
84e0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
84f0: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
8500: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
8510: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
8520: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
8530: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
8540: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
8550: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
8560: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
8570: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
8580: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
8590: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
85a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
85b0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
85c0: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
85d0: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
85e0: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
85f0: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
8600: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
8610: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
8620: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
8630: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
8640: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
8650: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
8660: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
8670: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
8680: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
8690: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
86a0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
86b0: 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  on must insure t
86c0: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
86d0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
86e0: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
86f0: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
8700: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
8710: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
8720: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
8730: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
8740: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
8750: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
8760: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
8770: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
8780: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
8790: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
87a0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
87b0: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
87c0: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
87d0: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
87e0: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
87f0: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
8800: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
8810: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
8820: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
8830: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
8840: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
8850: 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l>.*/.SQLITE_API
8860: 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65   int sqlite3_exe
8870: 63 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20  c(.  sqlite3*,  
8880: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8890: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
88a0: 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
88b0: 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
88c0: 68 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20  har *sql,       
88d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
88e0: 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
88f0: 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
8900: 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28  int (*callback)(
8910: 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a  void*,int,char**
8920: 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61  ,char**),  /* Ca
8930: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
8940: 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20  */.  void *,    
8950: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8960: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8970: 2f 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  /* 1st argument 
8980: 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20  to callback */. 
8990: 20 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20   char **errmsg  
89a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
89b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45              /* E
89c0: 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
89d0: 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   here */.);../*.
89e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73  ** CAPI3REF: Res
89f0: 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59  ult Codes.** KEY
8a00: 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b  WORDS: SQLITE_OK
8a10: 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65   {error code} {e
8a20: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
8a30: 45 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74  EYWORDS: {result
8a40: 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63   code} {result c
8a50: 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79  odes}.**.** Many
8a60: 20 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e   SQLite function
8a70: 73 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65  s return an inte
8a80: 67 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20  ger result code 
8a90: 66 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f  from the set sho
8aa0: 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72  wn.** here in or
8ab0: 64 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20  der to indicate 
8ac0: 73 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75  success or failu
8ad0: 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72  re..**.** New er
8ae0: 72 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65  ror codes may be
8af0: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
8b00: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
8b10: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ite..**.** See a
8b20: 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45  lso: [SQLITE_IOE
8b30: 52 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64  RR_READ | extend
8b40: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
8b50: 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74  ,.** [sqlite3_vt
8b60: 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29  ab_on_conflict()
8b70: 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  ] [SQLITE_ROLLBA
8b80: 43 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65  CK | result code
8b90: 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s]..*/.#define S
8ba0: 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20  QLITE_OK        
8bb0: 20 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73     0   /* Succes
8bc0: 73 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f  sful result */./
8bd0: 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65  * beginning-of-e
8be0: 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64  rror-codes */.#d
8bf0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52  efine SQLITE_ERR
8c00: 4f 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a  OR        1   /*
8c10: 20 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69   SQL error or mi
8c20: 73 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a  ssing database *
8c30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8c40: 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20  _INTERNAL     2 
8c50: 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f    /* Internal lo
8c60: 67 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c  gic error in SQL
8c70: 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ite */.#define S
8c80: 51 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20  QLITE_PERM      
8c90: 20 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73     3   /* Access
8ca0: 20 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69   permission deni
8cb0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
8cc0: 4c 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20  LITE_ABORT      
8cd0: 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63    4   /* Callbac
8ce0: 6b 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73  k routine reques
8cf0: 74 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a  ted an abort */.
8d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
8d10: 55 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20  USY         5   
8d20: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
8d30: 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  file is locked *
8d40: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8d50: 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20  _LOCKED       6 
8d60: 20 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20    /* A table in 
8d70: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
8d80: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
8d90: 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20  e SQLITE_NOMEM  
8da0: 20 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d        7   /* A m
8db0: 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a  alloc() failed *
8dc0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8dd0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20  _READONLY     8 
8de0: 20 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20    /* Attempt to 
8df0: 77 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79  write a readonly
8e00: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
8e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
8e20: 52 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20  RRUPT    9   /* 
8e30: 4f 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e  Operation termin
8e40: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
8e50: 69 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64  interrupt()*/.#d
8e60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
8e70: 52 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a  RR       10   /*
8e80: 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69   Some kind of di
8e90: 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63  sk I/O error occ
8ea0: 75 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  urred */.#define
8eb0: 20 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20   SQLITE_CORRUPT 
8ec0: 20 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20      11   /* The 
8ed0: 64 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d  database disk im
8ee0: 61 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64  age is malformed
8ef0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
8f00: 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31  TE_NOTFOUND    1
8f10: 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f  2   /* Unknown o
8f20: 70 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33  pcode in sqlite3
8f30: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20  _file_control() 
8f40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8f50: 45 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33  E_FULL        13
8f60: 20 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20     /* Insertion 
8f70: 66 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64  failed because d
8f80: 61 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20  atabase is full 
8f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8fa0: 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34  E_CANTOPEN    14
8fb0: 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20     /* Unable to 
8fc0: 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  open the databas
8fd0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
8fe0: 65 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f  e SQLITE_PROTOCO
8ff0: 4c 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74  L    15   /* Dat
9000: 61 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f  abase lock proto
9010: 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  col error */.#de
9020: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54  fine SQLITE_EMPT
9030: 59 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20  Y       16   /* 
9040: 44 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74  Database is empt
9050: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
9060: 49 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20  ITE_SCHEMA      
9070: 31 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61  17   /* The data
9080: 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
9090: 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ged */.#define S
90a0: 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20  QLITE_TOOBIG    
90b0: 20 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67    18   /* String
90c0: 20 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73   or BLOB exceeds
90d0: 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23   size limit */.#
90e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
90f0: 4e 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f  NSTRAINT  19   /
9100: 2a 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63  * Abort due to c
9110: 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74  onstraint violat
9120: 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ion */.#define S
9130: 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20  QLITE_MISMATCH  
9140: 20 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74    20   /* Data t
9150: 79 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a  ype mismatch */.
9160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d  #define SQLITE_M
9170: 49 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20  ISUSE      21   
9180: 2f 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20  /* Library used 
9190: 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23  incorrectly */.#
91a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
91b0: 4c 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f  LFS       22   /
91c0: 2a 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72  * Uses OS featur
91d0: 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64  es not supported
91e0: 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66   on host */.#def
91f0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20  ine SQLITE_AUTH 
9200: 20 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41         23   /* A
9210: 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e  uthorization den
9220: 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ied */.#define S
9230: 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20  QLITE_FORMAT    
9240: 20 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69    24   /* Auxili
9250: 61 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72  ary database for
9260: 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65  mat error */.#de
9270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47  fine SQLITE_RANG
9280: 45 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20  E       25   /* 
9290: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  2nd parameter to
92a0: 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75   sqlite3_bind ou
92b0: 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64  t of range */.#d
92c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
92d0: 41 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a  ADB      26   /*
92e0: 20 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61   File opened tha
92f0: 74 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  t is not a datab
9300: 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66  ase file */.#def
9310: 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20  ine SQLITE_ROW  
9320: 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73         100  /* s
9330: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61  qlite3_step() ha
9340: 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65  s another row re
9350: 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ady */.#define S
9360: 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20  QLITE_DONE      
9370: 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65    101  /* sqlite
9380: 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e  3_step() has fin
9390: 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20  ished executing 
93a0: 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72  */./* end-of-err
93b0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a  or-codes */../*.
93c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
93d0: 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64  ended Result Cod
93e0: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
93f0: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
9400: 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20  code} {extended 
9410: 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20  error codes}.** 
9420: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
9430: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d  ded result code}
9440: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
9450: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49  t codes}.**.** I
9460: 6e 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f  n its default co
9470: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c  nfiguration, SQL
9480: 69 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73  ite API routines
9490: 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32   return one of 2
94a0: 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51  6 integer.** [SQ
94b0: 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74  LITE_OK | result
94c0: 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65   codes].  Howeve
94d0: 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61  r, experience ha
94e0: 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e  s shown that man
94f0: 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65  y of.** these re
9500: 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74  sult codes are t
9510: 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65  oo coarse-graine
9520: 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20  d.  They do not 
9530: 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75  provide as.** mu
9540: 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  ch information a
9550: 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73  bout problems as
9560: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
9570: 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20  ht like.  In an 
9580: 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64  effort to.** add
9590: 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72  ress this, newer
95a0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
95b0: 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33  ite (version 3.3
95c0: 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e  .8 and later) in
95d0: 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74  clude.** support
95e0: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
95f0: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61  result codes tha
9600: 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64  t provide more d
9610: 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74  etailed informat
9620: 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72  ion.** about err
9630: 6f 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65  ors. The extende
9640: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61  d result codes a
9650: 72 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  re enabled or di
9660: 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70  sabled.** on a p
9670: 65 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  er database conn
9680: 65 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69  ection basis usi
9690: 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
96a0: 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
96b0: 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e  lt_codes()] API.
96c0: 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74  .**.** Some of t
96d0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74  he available ext
96e0: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
96f0: 65 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65  es are listed he
9700: 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65  re..** One may e
9710: 78 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72  xpect the number
9720: 20 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73   of extended res
9730: 75 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62  ult codes will b
9740: 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72  e expand.** over
9750: 20 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65   time.  Software
9760: 20 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e   that uses exten
9770: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
9780: 20 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a   should expect.*
9790: 2a 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73  * to see new res
97a0: 75 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74  ult codes in fut
97b0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20  ure releases of 
97c0: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  SQLite..**.** Th
97d0: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75  e SQLITE_OK resu
97e0: 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76  lt code will nev
97f0: 65 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20  er be extended. 
9800: 20 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a   It will always.
9810: 2a 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65  ** be exactly ze
9820: 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ro..*/.#define S
9830: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44  QLITE_IOERR_READ
9840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53                (S
9850: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31  QLITE_IOERR | (1
9860: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9870: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
9880: 5f 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51  _READ        (SQ
9890: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c  LITE_IOERR | (2<
98a0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
98b0: 49 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20  ITE_IOERR_WRITE 
98c0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
98d0: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c  ITE_IOERR | (3<<
98e0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
98f0: 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20  TE_IOERR_FSYNC  
9900: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
9910: 54 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38  TE_IOERR | (4<<8
9920: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9930: 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e  E_IOERR_DIR_FSYN
9940: 43 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  C         (SQLIT
9950: 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29  E_IOERR | (5<<8)
9960: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
9970: 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20  _IOERR_TRUNCATE 
9980: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
9990: 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29  _IOERR | (6<<8))
99a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
99b0: 49 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20  IOERR_FSTAT     
99c0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
99d0: 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a  IOERR | (7<<8)).
99e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
99f0: 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  OERR_UNLOCK     
9a00: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
9a10: 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23  OERR | (8<<8)).#
9a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9a30: 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20  ERR_RDLOCK      
9a40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9a50: 45 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64  ERR | (9<<8)).#d
9a60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9a70: 52 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  RR_DELETE       
9a80: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9a90: 52 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64  RR | (10<<8)).#d
9aa0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9ab0: 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20  RR_BLOCKED      
9ac0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9ad0: 52 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64  RR | (11<<8)).#d
9ae0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9af0: 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  RR_NOMEM        
9b00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9b10: 52 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64  RR | (12<<8)).#d
9b20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9b30: 52 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20  RR_ACCESS       
9b40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9b50: 52 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64  RR | (13<<8)).#d
9b60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9b70: 52 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44  RR_CHECKRESERVED
9b80: 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45  LOCK (SQLITE_IOE
9b90: 52 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64  RR | (14<<8)).#d
9ba0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9bb0: 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  RR_LOCK         
9bc0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9bd0: 52 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64  RR | (15<<8)).#d
9be0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9bf0: 52 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20  RR_CLOSE        
9c00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9c10: 52 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64  RR | (16<<8)).#d
9c20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9c30: 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20  RR_DIR_CLOSE    
9c40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9c50: 52 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64  RR | (17<<8)).#d
9c60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9c70: 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20  RR_SHMOPEN      
9c80: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9c90: 52 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64  RR | (18<<8)).#d
9ca0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9cb0: 52 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20  RR_SHMSIZE      
9cc0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9cd0: 52 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64  RR | (19<<8)).#d
9ce0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9cf0: 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20  RR_SHMLOCK      
9d00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9d10: 52 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64  RR | (20<<8)).#d
9d20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9d30: 52 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20  RR_SHMMAP       
9d40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9d50: 52 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64  RR | (21<<8)).#d
9d60: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9d70: 52 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20  RR_SEEK         
9d80: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9d90: 52 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64  RR | (22<<8)).#d
9da0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
9db0: 4b 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20  KED_SHAREDCACHE 
9dc0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43       (SQLITE_LOC
9dd0: 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  KED |  (1<<8)).#
9de0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
9df0: 53 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20  SY_RECOVERY     
9e00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55        (SQLITE_BU
9e10: 53 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a  SY   |  (1<<8)).
9e20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
9e30: 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49  ANTOPEN_NOTEMPDI
9e40: 52 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43  R      (SQLITE_C
9e50: 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29  ANTOPEN | (1<<8)
9e60: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
9e70: 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20  _CANTOPEN_ISDIR 
9e80: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
9e90: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c  _CANTOPEN | (2<<
9ea0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
9eb0: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
9ec0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
9ed0: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
9ee0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9ef0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
9f00: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
9f10: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
9f20: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
9f30: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
9f40: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
9f50: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
9f60: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
9f70: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f   SQLITE_ABORT_RO
9f80: 4c 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20  LLBACK          
9f90: 28 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20  (SQLITE_ABORT | 
9fa0: 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (2<<8))../*.** C
9fb0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
9fc0: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
9fd0: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
9fe0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
9ff0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
a000: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
a010: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
a020: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
a030: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
a040: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
a050: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
a060: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
a070: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
a080: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a090: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
a0a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a0b0: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
a0c0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a0d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a0e0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
a0f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a100: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
a110: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a120: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a130: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
a140: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a150: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
a160: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a170: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a180: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
a190: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
a1a0: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
a1b0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a1c0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
a1d0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a1e0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
a1f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a200: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
a210: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a220: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
a230: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a240: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
a250: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a260: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
a270: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a280: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a290: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
a2a0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
a2b0: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
a2c0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a2d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a2e0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
a2f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
a300: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a310: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a320: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
a330: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
a340: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a350: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a360: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
a370: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
a380: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a390: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a3a0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
a3b0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
a3c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a3d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a3e0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
a3f0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
a400: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a410: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a420: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
a430: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
a440: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a450: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a460: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
a470: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
a480: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a490: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a4a0: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
a4b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
a4c0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
a4d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a4e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a4f0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
a500: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
a510: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
a520: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a530: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a540: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
a550: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
a560: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
a570: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a580: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a590: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
a5a0: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
a5b0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
a5c0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
a5d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a5e0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
a5f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
a600: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
a610: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* Reserved:
a620: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
a630: 20 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30           0x00F00
a640: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
a650: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
a660: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
a670: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
a680: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
a690: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
a6a0: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
a6b0: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
a6c0: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
a6d0: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
a6e0: 72 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a  r of the these.*
a6f0: 2a 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70  * bit values exp
a700: 72 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72  ressing I/O char
a710: 61 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74  acteristics of t
a720: 68 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a  he mass storage.
a730: 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68  ** device that h
a740: 6f 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68  olds the file th
a750: 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  at the [sqlite3_
a760: 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72  io_methods].** r
a770: 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20  efers to..**.** 
a780: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
a790: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
a7a0: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
a7b0: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
a7c0: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
a7d0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
a7e0: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
a7f0: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
a800: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
a810: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
a820: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
a830: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
a840: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
a850: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
a860: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
a870: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
a880: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
a890: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
a8a0: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
a8b0: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
a8c0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
a8d0: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
a8e0: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
a8f0: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
a900: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
a910: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
a920: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
a930: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
a940: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
a950: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
a960: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
a970: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
a980: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
a990: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
a9a0: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
a9b0: 69 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49  ite().  The SQLI
a9c0: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
a9d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f  FE_OVERWRITE pro
a9e0: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
a9f0: 0a 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74  .** after reboot
aa00: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61   following a cra
aa10: 73 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73  sh or power loss
aa20: 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73  , the only bytes
aa30: 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68   in a.** file th
aa40: 61 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20  at were written 
aa50: 61 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  at the applicati
aa60: 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68  on level might h
aa70: 61 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61  ave changed.** a
aa80: 6e 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74  nd that adjacent
aa90: 20 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74   bytes, even byt
aaa0: 65 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61  es within the sa
aab0: 6d 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a  me sector are.**
aac0: 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62   guaranteed to b
aad0: 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a  e unchanged..*/.
aae0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
aaf0: 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20  OCAP_ATOMIC     
ab00: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
ab10: 30 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53  000001.#define S
ab20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
ab30: 49 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20  IC512           
ab40: 20 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64     0x00000002.#d
ab50: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
ab60: 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20  AP_ATOMIC1K     
ab70: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
ab80: 30 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c  0004.#define SQL
ab90: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
aba0: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
abb0: 20 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66   0x00000008.#def
abc0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
abd0: 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20  _ATOMIC4K       
abe0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
abf0: 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  10.#define SQLIT
ac00: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
ac10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
ac20: 78 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e  x00000020.#defin
ac30: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
ac40: 54 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20  TOMIC16K        
ac50: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
ac60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ac70: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20  IOCAP_ATOMIC32K 
ac80: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
ac90: 30 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20  0000080.#define 
aca0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
acb0: 4d 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20  MIC64K          
acc0: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23      0x00000100.#
acd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
ace0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
acf0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
ad00: 30 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51  00200.#define SQ
ad10: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
ad20: 4e 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20  NTIAL           
ad30: 20 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65    0x00000400.#de
ad40: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
ad50: 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48  P_UNDELETABLE_WH
ad60: 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30  EN_OPEN  0x00000
ad70: 38 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  800.#define SQLI
ad80: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
ad90: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
ada0: 30 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a  0x00001000../*.*
adb0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65  * CAPI3REF: File
adc0: 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a   Locking Levels.
add0: 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
ade0: 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69  s one of these i
adf0: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
ae00: 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61   the second.** a
ae10: 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73  rgument to calls
ae20: 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65   it makes to the
ae30: 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e   xLock() and xUn
ae40: 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a  lock() methods.*
ae50: 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  * of an [sqlite3
ae60: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
ae70: 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ect..*/.#define 
ae80: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
ae90: 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66            0.#def
aea0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
aeb0: 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a  SHARED        1.
aec0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
aed0: 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20  OCK_RESERVED    
aee0: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
aef0: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20  TE_LOCK_PENDING 
af00: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
af10: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
af20: 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a  USIVE     4../*.
af30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e  ** CAPI3REF: Syn
af40: 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70  chronization Typ
af50: 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68  e Flags.**.** Wh
af60: 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65  en SQLite invoke
af70: 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65  s the xSync() me
af80: 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73  thod of an.** [s
af90: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
afa0: 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65  s] object it use
afb0: 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20  s a combination 
afc0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65  of.** these inte
afd0: 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68  ger values as th
afe0: 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
aff0: 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  t..**.** When th
b000: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
b010: 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75  TAONLY flag is u
b020: 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  sed, it means th
b030: 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f  at the.** sync o
b040: 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65  peration only ne
b050: 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74  eds to flush dat
b060: 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67  a to mass storag
b070: 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66  e.  Inode.** inf
b080: 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f  ormation need no
b090: 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66  t be flushed. If
b0a0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
b0b0: 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67  bits of the flag
b0c0: 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45  .** equal SQLITE
b0d0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68  _SYNC_NORMAL, th
b0e0: 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20  at means to use 
b0f0: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73  normal fsync() s
b100: 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20  emantics..** If 
b110: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
b120: 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45  its equal SQLITE
b130: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74  _SYNC_FULL, that
b140: 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65   means.** to use
b150: 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20   Mac OS X style 
b160: 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64  fullsync instead
b170: 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a   of fsync()..**.
b180: 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73  ** Do not confus
b190: 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e  e the SQLITE_SYN
b1a0: 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c  C_NORMAL and SQL
b1b0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c  ITE_SYNC_FULL fl
b1c0: 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ags.** with the 
b1d0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
b1e0: 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20  ous]=NORMAL and 
b1f0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
b200: 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74  ous]=FULL.** set
b210: 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e  tings.  The [syn
b220: 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d  chronous pragma]
b230: 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e   determines when
b240: 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a   calls to the.**
b250: 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f   xSync VFS metho
b260: 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c  d occur and appl
b270: 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63  ies uniformly ac
b280: 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72  ross all platfor
b290: 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  ms..** The SQLIT
b2a0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e  E_SYNC_NORMAL an
b2b0: 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  d SQLITE_SYNC_FU
b2c0: 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69  LL flags determi
b2d0: 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65  ne how.** energe
b2e0: 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20  tic or rigorous 
b2f0: 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20  or forceful the 
b300: 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20  sync operations 
b310: 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20  are and.** only 
b320: 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63  make a differenc
b330: 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72  e on Mac OSX for
b340: 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c   the default SQL
b350: 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68  ite code..** (Th
b360: 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d  ird-party VFS im
b370: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69  plementations mi
b380: 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68  ght also make th
b390: 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a  e distinction.**
b3a0: 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f   between SQLITE_
b3b0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
b3c0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
b3d0: 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a  , but among the.
b3e0: 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  ** operating sys
b3f0: 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75  tems natively su
b400: 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
b410: 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a  e, only Mac OSX.
b420: 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74  ** cares about t
b430: 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a  he difference.).
b440: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b450: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20  E_SYNC_NORMAL   
b460: 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65       0x00002.#de
b470: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
b480: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30  _FULL          0
b490: 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53  x00003.#define S
b4a0: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
b4b0: 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30  NLY      0x00010
b4c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b4d0: 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f  : OS Interface O
b4e0: 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a  pen File Handle.
b4f0: 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65  **.** An [sqlite
b500: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72  3_file] object r
b510: 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65  epresents an ope
b520: 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a  n file in the .*
b530: 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  * [sqlite3_vfs |
b540: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61   OS interface la
b550: 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61  yer].  Individua
b560: 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a  l OS interface.*
b570: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
b580: 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74  s will.** want t
b590: 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20  o subclass this 
b5a0: 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64  object by append
b5b0: 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ing additional f
b5c0: 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65  ields.** for the
b5d0: 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65  ir own use.  The
b5e0: 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20   pMethods entry 
b5f0: 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
b600: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
b610: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
b620: 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d  t that defines m
b630: 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f  ethods for perfo
b640: 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65  rming.** I/O ope
b650: 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f  rations on the o
b660: 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70  pen file..*/.typ
b670: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
b680: 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33  te3_file sqlite3
b690: 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71  _file;.struct sq
b6a0: 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63  lite3_file {.  c
b6b0: 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69  onst struct sqli
b6c0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a  te3_io_methods *
b6d0: 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65  pMethods;  /* Me
b6e0: 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65  thods for an ope
b6f0: 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  n file */.};../*
b700: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
b710: 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20   Interface File 
b720: 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20  Virtual Methods 
b730: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65  Object.**.** Eve
b740: 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62  ry file opened b
b750: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  y the [sqlite3_v
b760: 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64  fs.xOpen] method
b770: 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a   populates an.**
b780: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
b790: 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65  object (or, more
b7a0: 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62   commonly, a sub
b7b0: 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20  class of the.** 
b7c0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
b7d0: 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f  bject) with a po
b7e0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74  inter to an inst
b7f0: 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
b800: 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a  ect..** This obj
b810: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
b820: 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20  methods used to 
b830: 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
b840: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67  operations.** ag
b850: 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66  ainst the open f
b860: 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20  ile represented 
b870: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
b880: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  file] object..**
b890: 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69  .** If the [sqli
b8a0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
b8b0: 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73  ethod sets the s
b8c0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
b8d0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a  hods element .**
b8e0: 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   to a non-NULL p
b8f0: 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65  ointer, then the
b900: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
b910: 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f  ods.xClose metho
b920: 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f  d.** may be invo
b930: 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20  ked even if the 
b940: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
b950: 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61  en] reported tha
b960: 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68  t it failed.  Th
b970: 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f  e.** only way to
b980: 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20   prevent a call 
b990: 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77  to xClose follow
b9a0: 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71  ing a failed [sq
b9b0: 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d  lite3_vfs.xOpen]
b9c0: 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b  .** is for the [
b9d0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
b9e0: 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71  n] to set the sq
b9f0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
ba00: 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74  ods element.** t
ba10: 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o NULL..**.** Th
ba20: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
ba30: 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65   to xSync may be
ba40: 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
ba50: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a  SYNC_NORMAL] or.
ba60: 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ** [SQLITE_SYNC_
ba70: 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73  FULL].  The firs
ba80: 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20  t choice is the 
ba90: 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a  normal fsync()..
baa0: 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68  ** The second ch
bab0: 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53  oice is a Mac OS
bac0: 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e   X style fullsyn
bad0: 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  c.  The [SQLITE_
bae0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a  SYNC_DATAONLY].*
baf0: 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52  * flag may be OR
bb00: 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74  ed in to indicat
bb10: 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20  e that only the 
bb20: 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65  data of the file
bb30: 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20  .** and not its 
bb40: 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62  inode needs to b
bb50: 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20  e synced..**.** 
bb60: 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  The integer valu
bb70: 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e  es to xLock() an
bb80: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20  d xUnlock() are 
bb90: 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a  one of.** <ul>.*
bba0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
bbb0: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c  OCK_NONE],.** <l
bbc0: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
bbd0: 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SHARED],.** <li>
bbe0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45   [SQLITE_LOCK_RE
bbf0: 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e  SERVED],.** <li>
bc00: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
bc10: 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  NDING], or.** <l
bc20: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
bc30: 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c  EXCLUSIVE]..** <
bc40: 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20  /ul>.** xLock() 
bc50: 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f  increases the lo
bc60: 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65  ck. xUnlock() de
bc70: 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b  creases the lock
bc80: 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52  ..** The xCheckR
bc90: 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65  eservedLock() me
bca0: 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74  thod checks whet
bcb0: 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65  her any database
bcc0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20   connection,.** 
bcd0: 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70  either in this p
bce0: 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d  rocess or in som
bcf0: 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c  e other process,
bd00: 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45   is holding a RE
bd10: 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49  SERVED,.** PENDI
bd20: 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45  NG, or EXCLUSIVE
bd30: 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c   lock on the fil
bd40: 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74  e.  It returns t
bd50: 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61  rue.** if such a
bd60: 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64   lock exists and
bd70: 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65   false otherwise
bd80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c  ..**.** The xFil
bd90: 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f  eControl() metho
bda0: 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69  d is a generic i
bdb0: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c  nterface that al
bdc0: 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56  lows custom.** V
bdd0: 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
bde0: 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63  ns to directly c
bdf0: 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66  ontrol an open f
be00: 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ile using the.**
be10: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
be20: 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66  ontrol()] interf
be30: 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  ace.  The second
be40: 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69   "op" argument i
be50: 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  s an.** integer 
be60: 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69  opcode.  The thi
be70: 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  rd argument is a
be80: 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72   generic pointer
be90: 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20   intended to.** 
bea0: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63  point to a struc
beb0: 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f  ture that may co
bec0: 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20  ntain arguments 
bed0: 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63  or space in whic
bee0: 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65  h to.** write re
bef0: 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f  turn values.  Po
bf00: 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72  tential uses for
bf10: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20   xFileControl() 
bf20: 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63  might be.** func
bf30: 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20  tions to enable 
bf40: 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77  blocking locks w
bf50: 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f  ith timeouts, to
bf60: 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c   change the.** l
bf70: 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20  ocking strategy 
bf80: 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20  (for example to 
bf90: 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63  use dot-file loc
bfa0: 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a  ks), to inquire.
bfb0: 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61  ** about the sta
bfc0: 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f  tus of a lock, o
bfd0: 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65  r to break stale
bfe0: 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c   locks.  The SQL
bff0: 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65  ite.** core rese
c000: 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73  rves all opcodes
c010: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66   less than 100 f
c020: 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a  or its own use..
c030: 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ** A [SQLITE_FCN
c040: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c  TL_LOCKSTATE | l
c050: 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20  ist of opcodes] 
c060: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73  less than 100 is
c070: 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41   available..** A
c080: 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
c090: 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d   define a custom
c0a0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
c0b0: 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20  thod should use 
c0c0: 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74  opcodes.** great
c0d0: 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61  er than 100 to a
c0e0: 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20  void conflicts. 
c0f0: 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
c100: 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72  ions should.** r
c110: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  eturn [SQLITE_NO
c120: 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65  TFOUND] for file
c130: 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73   control opcodes
c140: 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
c150: 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a  t.** recognize..
c160: 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f  **.** The xSecto
c170: 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72  rSize() method r
c180: 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f  eturns the secto
c190: 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a  r size of the.**
c1a0: 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64   device that und
c1b0: 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e  erlies the file.
c1c0: 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a    The sector siz
c1d0: 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69  e is the.** mini
c1e0: 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63  mum write that c
c1f0: 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20  an be performed 
c200: 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69  without disturbi
c210: 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65  ng.** other byte
c220: 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  s in the file.  
c230: 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61  The xDeviceChara
c240: 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20  cteristics().** 
c250: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61  method returns a
c260: 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63   bit vector desc
c270: 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73  ribing behaviors
c280: 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72   of the.** under
c290: 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a  lying device:.**
c2a0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
c2b0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
c2c0: 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  TOMIC].** <li> [
c2d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
c2e0: 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC512].** <li> 
c2f0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
c300: 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC1K].** <li> 
c310: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
c320: 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC2K].** <li> 
c330: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
c340: 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC4K].** <li> 
c350: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
c360: 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  OMIC8K].** <li> 
c370: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
c380: 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC16K].** <li>
c390: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
c3a0: 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC32K].** <li
c3b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
c3c0: 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC64K].** <l
c3d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
c3e0: 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a  _SAFE_APPEND].**
c3f0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
c400: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a  CAP_SEQUENTIAL].
c410: 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
c420: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
c430: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
c440: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
c450: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
c460: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
c470: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
c480: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
c490: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
c4a0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
c4b0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
c4c0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
c4d0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
c4e0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
c4f0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
c500: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
c510: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
c520: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
c530: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
c540: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
c550: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
c560: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
c570: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
c580: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
c590: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
c5a0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
c5b0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
c5c0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
c5d0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
c5e0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
c5f0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
c600: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
c610: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
c620: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
c630: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
c640: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
c650: 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78  te()..**.** If x
c660: 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53  Read() returns S
c670: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52  QLITE_IOERR_SHOR
c680: 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61  T_READ it must a
c690: 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74  lso fill.** in t
c6a0: 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f  he unread portio
c6b0: 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ns of the buffer
c6c0: 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20   with zeros.  A 
c6d0: 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c  VFS that.** fail
c6e0: 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73  s to zero-fill s
c6f0: 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74  hort reads might
c700: 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20   seem to work.  
c710: 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c  However,.** fail
c720: 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c  ure to zero-fill
c730: 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c   short reads wil
c740: 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61  l eventually lea
c750: 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65  d to.** database
c760: 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
c770: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
c780: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
c790: 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  s sqlite3_io_met
c7a0: 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
c7b0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
c7c0: 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
c7d0: 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65  ;.  int (*xClose
c7e0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29  )(sqlite3_file*)
c7f0: 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29  ;.  int (*xRead)
c800: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
c810: 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c  void*, int iAmt,
c820: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69   sqlite3_int64 i
c830: 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Ofst);.  int (*x
c840: 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66  Write)(sqlite3_f
c850: 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ile*, const void
c860: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
c870: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
c880: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e  );.  int (*xTrun
c890: 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  cate)(sqlite3_fi
c8a0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
c8b0: 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20  64 size);.  int 
c8c0: 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33  (*xSync)(sqlite3
c8d0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67  _file*, int flag
c8e0: 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  s);.  int (*xFil
c8f0: 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66  eSize)(sqlite3_f
c900: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
c910: 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69  t64 *pSize);.  i
c920: 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69  nt (*xLock)(sqli
c930: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
c940: 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b  .  int (*xUnlock
c950: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
c960: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
c970: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
c980: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
c990: 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b  , int *pResOut);
c9a0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f  .  int (*xFileCo
c9b0: 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66  ntrol)(sqlite3_f
c9c0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f  ile*, int op, vo
c9d0: 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74  id *pArg);.  int
c9e0: 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28   (*xSectorSize)(
c9f0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
ca00: 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43    int (*xDeviceC
ca10: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28  haracteristics)(
ca20: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a  sqlite3_file*);.
ca30: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
ca40: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
ca50: 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20   version 1 */.  
ca60: 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73  int (*xShmMap)(s
ca70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
ca80: 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c  t iPg, int pgsz,
ca90: 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74   int, void volat
caa0: 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  ile**);.  int (*
cab0: 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65  xShmLock)(sqlite
cac0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66  3_file*, int off
cad0: 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20  set, int n, int 
cae0: 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28  flags);.  void (
caf0: 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71  *xShmBarrier)(sq
cb00: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
cb10: 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29  int (*xShmUnmap)
cb20: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
cb30: 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b  int deleteFlag);
cb40: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
cb50: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
cb60: 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20  r version 2 */. 
cb70: 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d   /* Additional m
cb80: 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64  ethods may be ad
cb90: 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
cba0: 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  leases */.};../*
cbb0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74  .** CAPI3REF: St
cbc0: 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74  andard File Cont
cbd0: 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a  rol Opcodes.**.*
cbe0: 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
cbf0: 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70  constants are op
cc00: 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46  codes for the xF
cc10: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
cc20: 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  d.** of the [sql
cc30: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
cc40: 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20   object and for 
cc50: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
cc60: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20  e_control()].** 
cc70: 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
cc80: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
cc90: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70  TL_LOCKSTATE] op
cca0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72  code is used for
ccb0: 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69   debugging.  Thi
ccc0: 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73  s.** opcode caus
ccd0: 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  es the xFileCont
cce0: 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72  rol method to wr
ccf0: 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20  ite the current 
cd00: 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20  state of.** the 
cd10: 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51  lock (one of [SQ
cd20: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
cd30: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48   [SQLITE_LOCK_SH
cd40: 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ARED],.** [SQLIT
cd50: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d  E_LOCK_RESERVED]
cd60: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  , [SQLITE_LOCK_P
cd70: 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c  ENDING], or [SQL
cd80: 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49  ITE_LOCK_EXCLUSI
cd90: 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20  VE]).** into an 
cda0: 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65  integer that the
cdb0: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70   pArg argument p
cdc0: 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63  oints to. This c
cdd0: 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
cde0: 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
cdf0: 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65  ing and only nee
ce00: 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ds to be support
ce10: 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54  ed when SQLITE_T
ce20: 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65  EST.** is define
ce30: 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  d..** <ul>.** <l
ce40: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
ce50: 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20  _SIZE_HINT]].** 
ce60: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
ce70: 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63  L_SIZE_HINT] opc
ce80: 6f 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53  ode is used by S
ce90: 51 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68  QLite to give th
cea0: 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61  e VFS.** layer a
ceb0: 20 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72   hint of how lar
cec0: 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ge the database 
ced0: 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74  file will grow t
cee0: 6f 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a  o be during the.
cef0: 2a 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  ** current trans
cf00: 61 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69  action.  This hi
cf10: 6e 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e  nt is not guaran
cf20: 74 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72  teed to be accur
cf30: 61 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73  ate but it.** is
cf40: 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54   often close.  T
cf50: 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46  he underlying VF
cf60: 53 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74  S might choose t
cf70: 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61  o preallocate da
cf80: 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73  tabase.** file s
cf90: 70 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68  pace based on th
cfa0: 69 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72  is hint in order
cfb0: 20 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20   to help writes 
cfc0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  to the database.
cfd0: 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74  ** file run fast
cfe0: 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  er..**.** <li>[[
cff0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55  SQLITE_FCNTL_CHU
d000: 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65  NK_SIZE]].** The
d010: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43   [SQLITE_FCNTL_C
d020: 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64  HUNK_SIZE] opcod
d030: 65 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71  e is used to req
d040: 75 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46  uest that the VF
d050: 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64  S.** extends and
d060: 20 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64   truncates the d
d070: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20  atabase file in 
d080: 63 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65  chunks of a size
d090: 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
d0a0: 20 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66   the user. The f
d0b0: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
d0c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  o [sqlite3_file_
d0d0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c  control()] shoul
d0e0: 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  d .** point to a
d0f0: 6e 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20  n integer (type 
d100: 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20  int) containing 
d110: 74 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69  the new chunk-si
d120: 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72  ze to use.** for
d130: 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64   the nominated d
d140: 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74  atabase. Allocat
d150: 69 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c  ing database fil
d160: 65 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65  e space in large
d170: 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20  .** chunks (say 
d180: 31 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20  1MB at a time), 
d190: 6d 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d  may reduce file-
d1a0: 73 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61  system fragmenta
d1b0: 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72  tion and.** impr
d1c0: 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ove performance 
d1d0: 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e  on some systems.
d1e0: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
d1f0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
d200: 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20  OINTER]].** The 
d210: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
d220: 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f  LE_POINTER] opco
d230: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62  de is used to ob
d240: 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a  tain a pointer.*
d250: 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
d260: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61  3_file] object a
d270: 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
d280: 20 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61   particular data
d290: 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
d2a0: 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71  on.  See the [sq
d2b0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
d2c0: 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74  ol()] documentat
d2d0: 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  ion for.** addit
d2e0: 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
d2f0: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
d300: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
d310: 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28  _OMITTED]].** ^(
d320: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d330: 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20  L_SYNC_OMITTED] 
d340: 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61  opcode is genera
d350: 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  ted internally b
d360: 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20  y.** SQLite and 
d370: 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65  sent to all VFSe
d380: 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20  s in place of a 
d390: 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e  call to the xSyn
d3a0: 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e  c method.** when
d3b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
d3c0: 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52  nnection has [PR
d3d0: 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73  AGMA synchronous
d3e0: 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a  ] set to OFF.)^.
d3f0: 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69  ** Some speciali
d400: 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74  zed VFSes need t
d410: 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72  his signal in or
d420: 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63  der to operate c
d430: 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e  orrectly.** when
d440: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
d450: 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79  nous | PRAGMA sy
d460: 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69  nchronous=OFF] i
d470: 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20  s set, but most 
d480: 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74  .** VFSes do not
d490: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
d4a0: 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c  l and should sil
d4b0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
d4c0: 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70  s opcode..** App
d4d0: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
d4e0: 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74   not call [sqlit
d4f0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
d500: 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20  )] with this.** 
d510: 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20  opcode as doing 
d520: 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74  so may disrupt t
d530: 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  he operation of 
d540: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
d550: 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f  VFSes.** that do
d560: 20 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a   require it.  .*
d570: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
d580: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
d590: 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65  _RETRY]].** ^The
d5a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57   [SQLITE_FCNTL_W
d5b0: 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f  IN32_AV_RETRY] o
d5c0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
d5d0: 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d   configure autom
d5e0: 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f  atic.** retry co
d5f0: 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61  unts and interva
d600: 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64  ls for certain d
d610: 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f  isk I/O operatio
d620: 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69  ns for the.** wi
d630: 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f  ndows [VFS] in o
d640: 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20  rder to provide 
d650: 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68  robustness in th
d660: 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a  e presence of.**
d670: 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67   anti-virus prog
d680: 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c  rams.  By defaul
d690: 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56  t, the windows V
d6a0: 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69  FS will retry fi
d6b0: 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65  le read,.** file
d6c0: 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65   write, and file
d6d0: 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f   delete operatio
d6e0: 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65  ns up to 10 time
d6f0: 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a  s, with a delay.
d700: 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65  ** of 25 millise
d710: 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65  conds before the
d720: 20 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64   first retry and
d730: 20 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20   with the delay 
d740: 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79  increasing.** by
d750: 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32   an additional 2
d760: 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77  5 milliseconds w
d770: 69 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75  ith each subsequ
d780: 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73  ent retry.  This
d790: 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77  .** opcode allow
d7a0: 73 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75  s these two valu
d7b0: 65 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61  es (10 retries a
d7c0: 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  nd 25 millisecon
d7d0: 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20  ds of delay).** 
d7e0: 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20  to be adjusted. 
d7f0: 20 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20   The values are 
d800: 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20  changed for all 
d810: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
d820: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74  ions.** within t
d830: 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e  he same process.
d840: 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69    The argument i
d850: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
d860: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a  n array of two.*
d870: 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65  * integers where
d880: 20 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67   the first integ
d890: 65 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74  er i the new ret
d8a0: 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65  ry count and the
d8b0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67   second.** integ
d8c0: 65 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e  er is the delay.
d8d0: 20 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65    If either inte
d8e0: 67 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c  ger is negative,
d8f0: 20 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e   then the settin
d900: 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e  g.** is not chan
d910: 67 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20  ged but instead 
d920: 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
d930: 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20  of that setting 
d940: 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e  is written.** in
d950: 74 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74  to the array ent
d960: 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65  ry, allowing the
d970: 20 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73   current retry s
d980: 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a  ettings to be.**
d990: 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20   interrogated.  
d9a0: 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61  The zDbName para
d9b0: 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64  meter is ignored
d9c0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
d9d0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49  LITE_FCNTL_PERSI
d9e0: 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65  ST_WAL]].** ^The
d9f0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
da00: 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f  ERSIST_WAL] opco
da10: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
da20: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
da30: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41  * persistent [WA
da40: 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20  L | Write Ahead 
da50: 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42  Log] setting.  B
da60: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61  y default, the a
da70: 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74  uxiliary.** writ
da80: 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20  e ahead log and 
da90: 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69  shared memory fi
daa0: 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61  les used for tra
dab0: 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c  nsaction control
dac0: 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69  .** are automati
dad0: 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68  cally deleted wh
dae0: 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f  en the latest co
daf0: 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20  nnection to the 
db00: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73  database.** clos
db10: 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72  es.  Setting per
db20: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
db30: 20 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69   causes those fi
db40: 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61  les to persist a
db50: 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20  fter.** close.  
db60: 50 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66  Persisting the f
db70: 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77  iles is useful w
db80: 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73  hen other proces
db90: 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a  ses that do not.
dba0: 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65  ** have write pe
dbb0: 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20  rmission on the 
dbc0: 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69  directory contai
dbd0: 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ning the databas
dbe0: 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74  e file want.** t
dbf0: 6f 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62  o read the datab
dc00: 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65  ase file, as the
dc10: 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20   WAL and shared 
dc20: 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73  memory files mus
dc30: 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72  t exist.** in or
dc40: 64 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61  der for the data
dc50: 62 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61  base to be reada
dc60: 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68  ble.  The fourth
dc70: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
dc80: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
dc90: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
dca0: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
dcb0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
dcc0: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
dcd0: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
dce0: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72  0 to disable per
dcf0: 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65  sistent WAL mode
dd00: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
dd10: 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41  persistent.** WA
dd20: 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  L mode.  If the 
dd30: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
dd40: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
dd50: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
dd60: 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65  urrent.** WAL pe
dd70: 72 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e  rsistence settin
dd80: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
dd90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
dda0: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
ddb0: 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ].** ^The [SQLIT
ddc0: 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46  E_FCNTL_POWERSAF
ddd0: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  E_OVERWRITE] opc
dde0: 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73  ode is used to s
ddf0: 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a  et or query the.
de00: 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70  ** persistent "p
de10: 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69  owersafe-overwri
de20: 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65  te" or "PSOW" se
de30: 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57  tting.  The PSOW
de40: 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65   setting.** dete
de50: 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49  rmines the [SQLI
de60: 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41  TE_IOCAP_POWERSA
de70: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69  FE_OVERWRITE] bi
de80: 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76  t of the.** xDev
de90: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
dea0: 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20  cs methods. The 
deb0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
dec0: 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
ded0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
dee0: 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20  for this opcode 
def0: 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e  should be a poin
df00: 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
df10: 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67  r..** That integ
df20: 65 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  er is 0 to disab
df30: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d  le zero-damage m
df40: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
df50: 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a  le zero-damage.*
df60: 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20  * mode.  If the 
df70: 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74  integer is -1, t
df80: 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72  hen it is overwr
df90: 69 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63  itten with the c
dfa0: 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64  urrent.** zero-d
dfb0: 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69  amage mode setti
dfc0: 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ng..**.** <li>[[
dfd0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45  SQLITE_FCNTL_OVE
dfe0: 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65  RWRITE]].** ^The
dff0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f   [SQLITE_FCNTL_O
e000: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
e010: 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53   is invoked by S
e020: 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e  QLite after open
e030: 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74  ing.** a write t
e040: 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e  ransaction to in
e050: 64 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c  dicate that, unl
e060: 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64  ess it is rolled
e070: 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a   back for some.*
e080: 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e  * reason, the en
e090: 74 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69  tire database fi
e0a0: 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77  le will be overw
e0b0: 72 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75  ritten by the cu
e0c0: 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61  rrent .** transa
e0d0: 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75  ction. This is u
e0e0: 73 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70  sed by VACUUM op
e0f0: 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
e100: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
e110: 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20  TL_VFSNAME]].** 
e120: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
e130: 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f  TL_VFSNAME] opco
e140: 64 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  de can be used t
e150: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d  o obtain the nam
e160: 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46  es of.** all [VF
e170: 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20  Ses] in the VFS 
e180: 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65  stack.  The name
e190: 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53  s are of all VFS
e1a0: 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a   shims and the.*
e1b0: 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c  * final bottom-l
e1c0: 65 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69  evel VFS are wri
e1d0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
e1e0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
e1f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
e200: 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65  oc()] and the re
e210: 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69  sult is stored i
e220: 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69  n the char* vari
e230: 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65  able.** that the
e240: 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
e250: 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69  r of [sqlite3_fi
e260: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f  le_control()] po
e270: 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20  ints to..** The 
e280: 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e  caller is respon
e290: 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e  sible for freein
e2a0: 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65  g the memory whe
e2b0: 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68  n done.  As with
e2c0: 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e  .** all file-con
e2d0: 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68  trol actions, th
e2e0: 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e  ere is no guaran
e2f0: 74 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69  tee that this wi
e300: 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64  ll actually.** d
e310: 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c  o anything.  Cal
e320: 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74  lers should init
e330: 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a  ialize the char*
e340: 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e   variable to a N
e350: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ULL.** pointer i
e360: 6e 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65  n case this file
e370: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20  -control is not 
e380: 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68  implemented.  Th
e390: 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a  is file-control.
e3a0: 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66  ** is intended f
e3b0: 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73  or diagnostic us
e3c0: 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  e only..**.** <l
e3d0: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
e3e0: 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68  _PRAGMA]].** ^Wh
e3f0: 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41  enever a [PRAGMA
e400: 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70  ] statement is p
e410: 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54  arsed, an [SQLIT
e420: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
e430: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
e440: 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20   is sent to the 
e450: 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  open [sqlite3_fi
e460: 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65  le] object corre
e470: 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74  sponding.** to t
e480: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
e490: 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72   to which the pr
e4a0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72  agma statement r
e4b0: 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75  efers. ^The argu
e4c0: 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ment.** to the [
e4d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
e4e0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
e4f0: 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  l is an array of
e500: 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
e510: 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29  strings (char**)
e520: 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65   in which the se
e530: 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20  cond element of 
e540: 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20  the array.** is 
e550: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
e560: 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74  pragma and the t
e570: 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20  hird element is 
e580: 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  the argument to 
e590: 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72  the.** pragma or
e5a0: 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61   NULL if the pra
e5b0: 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d  gma has no argum
e5c0: 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ent.  ^The handl
e5d0: 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51  er for an.** [SQ
e5e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
e5f0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
e600: 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d  can optionally m
e610: 61 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c  ake the first el
e620: 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20  ement.** of the 
e630: 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20  char** argument 
e640: 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
e650: 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  g obtained from 
e660: 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  [sqlite3_mprintf
e670: 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71  ()].** or the eq
e680: 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61  uivalent and tha
e690: 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65  t string will be
e6a0: 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20  come the result 
e6b0: 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72  of the pragma or
e6c0: 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65  .** the error me
e6d0: 73 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61  ssage if the pra
e6e0: 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74  gma fails. ^If t
e6f0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43  he.** [SQLITE_FC
e700: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
e710: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
e720: 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e   [SQLITE_NOTFOUN
e730: 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20  D], then normal 
e740: 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f  .** [PRAGMA] pro
e750: 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65  cessing continue
e760: 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c  s.  ^If the [SQL
e770: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
e780: 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f  ].** file contro
e790: 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  l returns [SQLIT
e7a0: 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20  E_OK], then the 
e7b0: 70 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74  parser assumes t
e7c0: 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68  hat the.** VFS h
e7d0: 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50  as handled the P
e7e0: 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64  RAGMA itself and
e7f0: 20 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65   the parser gene
e800: 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a  rates a no-op.**
e810: 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
e820: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ent.  ^If the [S
e830: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
e840: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
e850: 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
e860: 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65  result code othe
e870: 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f  r than [SQLITE_O
e880: 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f  K] or [SQLITE_NO
e890: 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65  TFOUND], that me
e8a0: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ans.** that the 
e8b0: 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20  VFS encountered 
e8c0: 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68  an error while h
e8d0: 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41  andling the [PRA
e8e0: 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20  GMA] and the.** 
e8f0: 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74  compilation of t
e900: 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20  he PRAGMA fails 
e910: 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20  with an error.  
e920: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e  ^The [SQLITE_FCN
e930: 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69  TL_PRAGMA].** fi
e940: 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72  le control occur
e950: 73 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69  s at the beginni
e960: 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61  ng of pragma sta
e970: 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20  tement analysis 
e980: 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20  and so.** it is 
e990: 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65  able to override
e9a0: 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d   built-in [PRAGM
e9b0: 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  A] statements..*
e9c0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
e9d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
e9e0: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
e9f0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
ea00: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
ea10: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
ea20: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
ea30: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
ea40: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
ea50: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
ea60: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
ea70: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  O               
ea80: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
ea90: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
eaa0: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
eab0: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
eac0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
ead0: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
eae0: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
eaf0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
eb00: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
eb10: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
eb20: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
eb30: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
eb40: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
eb50: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
eb60: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
eb70: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
eb80: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
eb90: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
eba0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
ebb0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
ebc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
ebd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
ebe0: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
ebf0: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
ec00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
ec10: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
ec20: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
ec30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
ec40: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
ec50: 20 20 20 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a            14../*
ec60: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
ec70: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
ec80: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
ec90: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
eca0: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
ecb0: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
ecc0: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
ecd0: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
ece0: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
ecf0: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
ed00: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
ed10: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
ed20: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
ed30: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
ed40: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
ed50: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
ed60: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
ed70: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
ed80: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
ed90: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
eda0: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
edb0: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
edc0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
edd0: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
ede0: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
edf0: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
ee00: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
ee10: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
ee20: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
ee30: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
ee40: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
ee50: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
ee60: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
ee70: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
ee80: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
ee90: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
eea0: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
eeb0: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
eec0: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
eed0: 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20  m".  See.** the 
eee0: 5b 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d  [VFS | VFS docum
eef0: 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75  entation] for fu
ef00: 72 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f  rther informatio
ef10: 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c  n..**.** The val
ef20: 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69  ue of the iVersi
ef30: 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74  on field is init
ef40: 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20  ially 1 but may 
ef50: 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20  be larger in.** 
ef60: 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
ef70: 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69  of SQLite.  Addi
ef80: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61  tional fields ma
ef90: 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f  y be appended to
efa0: 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20   this.** object 
efb0: 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f  when the iVersio
efc0: 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65  n value is incre
efd0: 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74  ased.  Note that
efe0: 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a   the structure.*
eff0: 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
f000: 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e  _vfs object chan
f010: 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73  ges in the trans
f020: 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a  action between.*
f030: 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  * SQLite version
f040: 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30   3.5.9 and 3.6.0
f050: 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65   and yet the iVe
f060: 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20  rsion field was 
f070: 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e  not.** modified.
f080: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46  .**.** The szOsF
f090: 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65  ile field is the
f0a0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62   size of the sub
f0b0: 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33  classed [sqlite3
f0c0: 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74  _file].** struct
f0d0: 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73  ure used by this
f0e0: 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d   VFS.  mxPathnam
f0f0: 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  e is the maximum
f100: 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20   length of.** a 
f110: 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73  pathname in this
f120: 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69   VFS..**.** Regi
f130: 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76  stered sqlite3_v
f140: 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b  fs objects are k
f150: 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20  ept on a linked 
f160: 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a  list formed by.*
f170: 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e  * the pNext poin
f180: 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ter.  The [sqlit
f190: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
f1a0: 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
f1b0: 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65  e3_vfs_unregiste
f1c0: 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20  r()] interfaces 
f1d0: 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74  manage this list
f1e0: 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d  .** in a thread-
f1f0: 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b  safe way.  The [
f200: 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64  sqlite3_vfs_find
f210: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ()] interface.**
f220: 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69   searches the li
f230: 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65  st.  Neither the
f240: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
f250: 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a  e nor the VFS.**
f260: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
f270: 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70  should use the p
f280: 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  Next pointer..**
f290: 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69  .** The pNext fi
f2a0: 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20  eld is the only 
f2b0: 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c  field in the sql
f2c0: 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75  ite3_vfs.** stru
f2d0: 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74  cture that SQLit
f2e0: 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69  e will ever modi
f2f0: 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c  fy.  SQLite will
f300: 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20   only access.** 
f310: 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66  or modify this f
f320: 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69  ield while holdi
f330: 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  ng a particular 
f340: 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a  static mutex..**
f350: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
f360: 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f   should never mo
f370: 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69  dify anything wi
f380: 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  thin the sqlite3
f390: 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f  _vfs.** object o
f3a0: 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68  nce the object h
f3b0: 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72  as been register
f3c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e  ed..**.** The zN
f3d0: 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20  ame field holds 
f3e0: 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
f3f0: 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65  VFS module.  The
f400: 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65   name must.** be
f410: 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61   unique across a
f420: 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a  ll VFS modules..
f430: 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f  **.** [[sqlite3_
f440: 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e  vfs.xOpen]].** ^
f450: 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
f460: 73 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65  s that the zFile
f470: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
f480: 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69  o xOpen.** is ei
f490: 74 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ther a NULL poin
f4a0: 74 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62  ter or string ob
f4b0: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78  tained.** from x
f4c0: 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77  FullPathname() w
f4d0: 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20  ith an optional 
f4e0: 73 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a  suffix added..**
f4f0: 20 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73   ^If a suffix is
f500: 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46   added to the zF
f510: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
f520: 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f  r, it will.** co
f530: 6e 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c  nsist of a singl
f540: 65 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20  e "-" character 
f550: 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d  followed by no m
f560: 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61  ore than.** 11 a
f570: 6c 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f  lphanumeric and/
f580: 6f 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72  or "-" character
f590: 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75  s..** ^SQLite fu
f5a0: 72 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73  rther guarantees
f5b0: 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72   that.** the str
f5c0: 69 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ing will be vali
f5d0: 64 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20  d and unchanged 
f5e0: 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69  until xClose() i
f5f0: 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63  s.** called. Bec
f600: 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76  ause of the prev
f610: 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a  ious sentence,.*
f620: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  * the [sqlite3_f
f630: 69 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20  ile] can safely 
f640: 73 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20  store a pointer 
f650: 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61  to the.** filena
f660: 6d 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74  me if it needs t
f670: 6f 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66  o remember the f
f680: 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65  ilename for some
f690: 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74   reason..** If t
f6a0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
f6b0: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20  ameter to xOpen 
f6c0: 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
f6d0: 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20  r then xOpen.** 
f6e0: 6d 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20  must invent its 
f6f0: 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61  own temporary na
f700: 6d 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e  me for the file.
f710: 20 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20    ^Whenever the 
f720: 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61  .** xFilename pa
f730: 72 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20  rameter is NULL 
f740: 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20  it will also be 
f750: 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
f760: 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d  e.** flags param
f770: 65 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64  eter will includ
f780: 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  e [SQLITE_OPEN_D
f790: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a  ELETEONCLOSE]..*
f7a0: 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61  *.** The flags a
f7b0: 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e  rgument to xOpen
f7c0: 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
f7d0: 62 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74  bits set in.** t
f7e0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
f7f0: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70  t to [sqlite3_op
f800: 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66  en_v2()].  Or if
f810: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
f820: 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33  ].** or [sqlite3
f830: 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73  _open16()] is us
f840: 65 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69  ed, then flags i
f850: 6e 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74  ncludes at least
f860: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
f870: 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53  _READWRITE] | [S
f880: 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
f890: 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e  E]. .** If xOpen
f8a0: 28 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20  () opens a file 
f8b0: 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69  read-only then i
f8c0: 74 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67  t sets *pOutFlag
f8d0: 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20  s to.** include 
f8e0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
f8f0: 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62  DONLY].  Other b
f900: 69 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67  its in *pOutFlag
f910: 73 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a  s may be set..**
f920: 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c  .** ^(SQLite wil
f930: 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f  l also add one o
f940: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
f950: 66 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70  flags to the xOp
f960: 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65  en().** call, de
f970: 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f  pending on the o
f980: 62 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e  bject being open
f990: 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ed:.**.** <ul>.*
f9a0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
f9b0: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a  OPEN_MAIN_DB].**
f9c0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
f9d0: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
f9e0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
f9f0: 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d  TE_OPEN_TEMP_DB]
fa00: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
fa10: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
fa20: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
fa30: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53  QLITE_OPEN_TRANS
fa40: 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  IENT_DB].** <li>
fa50: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53    [SQLITE_OPEN_S
fa60: 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  UBJOURNAL].** <l
fa70: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
fa80: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d  _MASTER_JOURNAL]
fa90: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
faa0: 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c  E_OPEN_WAL].** <
fab0: 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
fac0: 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d   file I/O implem
fad0: 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65  entation can use
fae0: 20 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65   the object type
faf0: 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61   flags to.** cha
fb00: 6e 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64  nge the way it d
fb10: 65 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e  eals with files.
fb20: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61    For example, a
fb30: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a  n application.**
fb40: 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63   that does not c
fb50: 61 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20  are about crash 
fb60: 72 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c  recovery or roll
fb70: 62 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a  back might make.
fb80: 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61  ** the open of a
fb90: 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20   journal file a 
fba0: 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74  no-op.  Writes t
fbb0: 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77  o this journal w
fbc0: 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20  ould.** also be 
fbd0: 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20  no-ops, and any 
fbe0: 61 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20  attempt to read 
fbf0: 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  the journal woul
fc00: 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49  d return.** SQLI
fc10: 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68  TE_IOERR.  Or th
fc20: 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
fc30: 20 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65   might recognize
fc40: 20 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65   that a database
fc50: 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65  .** file will be
fc60: 20 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67   doing page-alig
fc70: 6e 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73  ned sector reads
fc80: 20 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61   and writes in a
fc90: 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72   random.** order
fca0: 20 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20   and set up its 
fcb0: 49 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63  I/O subsystem ac
fcc0: 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a  cordingly..**.**
fcd0: 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c   SQLite might al
fce0: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
fcf0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
fd00: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d  s to the xOpen m
fd10: 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
fd20: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
fd30: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
fd40: 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  LOSE].** <li> [S
fd50: 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
fd60: 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  SIVE].** </ul>.*
fd70: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
fd80: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
fd90: 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20  OSE] flag means 
fda0: 74 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  the file should 
fdb0: 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68  be.** deleted wh
fdc0: 65 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e  en it is closed.
fdd0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f    ^The [SQLITE_O
fde0: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
fdf0: 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65  E].** will be se
fe00: 74 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62  t for TEMP datab
fe10: 61 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a  ases and their j
fe20: 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65  ournals, transie
fe30: 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c  nt.** databases,
fe40: 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73   and subjournals
fe50: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
fe60: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
fe70: 49 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77  IVE] flag is alw
fe80: 61 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a  ays used in conj
fe90: 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20  unction.** with 
fea0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
feb0: 5f 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77  _CREATE] flag, w
fec0: 68 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69  hich are both di
fed0: 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67  rectly.** analog
fee0: 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43  ous to the O_EXC
fef0: 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c  L and O_CREAT fl
ff00: 61 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58  ags of the POSIX
ff10: 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20   open().** API. 
ff20: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   The SQLITE_OPEN
ff30: 5f 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c  _EXCLUSIVE flag,
ff40: 20 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74   when paired wit
ff50: 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45  h the .** SQLITE
ff60: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73  _OPEN_CREATE, is
ff70: 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74   used to indicat
ff80: 65 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75  e that file shou
ff90: 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ld always.** be 
ffa0: 63 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61  created, and tha
ffb0: 74 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  t it is an error
ffc0: 20 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65   if it already e
ffd0: 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20  xists..** It is 
ffe0: 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20  <i>not</i> used 
fff0: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20  to indicate the 
10000 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f  file should be o
10010 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78  pened .** for ex
10020 63 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a  clusive access..
10030 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20  **.** ^At least 
10040 73 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f  szOsFile bytes o
10050 66 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c  f memory are all
10060 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65  ocated by SQLite
10070 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  .** to hold the 
10080 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
10090 73 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64  structure passed
100a0 20 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   as the third.**
100b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70   argument to xOp
100c0 65 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d  en.  The xOpen m
100d0 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68  ethod does not h
100e0 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61  ave to.** alloca
100f0 74 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65  te the structure
10100 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74  ; it should just
10110 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f   fill it in.  No
10120 74 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78  te that.** the x
10130 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74  Open method must
10140 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33   set the sqlite3
10150 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74  _file.pMethods t
10160 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61  o either.** a va
10170 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  lid [sqlite3_io_
10180 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
10190 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70  or to NULL.  xOp
101a0 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68  en must do.** th
101b0 69 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  is even if the o
101c0 70 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69  pen fails.  SQLi
101d0 74 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20  te expects that 
101e0 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  the sqlite3_file
101f0 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65  .pMethods.** ele
10200 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c  ment will be val
10210 69 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72  id after xOpen r
10220 65 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73  eturns regardles
10230 73 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73  s of the success
10240 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f  .** or failure o
10250 66 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c  f the xOpen call
10260 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65  ..**.** [[sqlite
10270 33 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a  3_vfs.xAccess]].
10280 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72  ** ^The flags ar
10290 67 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73  gument to xAcces
102a0 73 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49  s() may be [SQLI
102b0 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
102c0 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72  ].** to test for
102d0 20 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f   the existence o
102e0 66 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51  f a file, or [SQ
102f0 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
10300 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73  WRITE] to.** tes
10310 74 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65  t whether a file
10320 20 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64   is readable and
10330 20 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53   writable, or [S
10340 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
10350 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68  D].** to test wh
10360 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
10370 61 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c  at least readabl
10380 65 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61  e.   The file ca
10390 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74  n be a.** direct
103a0 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ory..**.** ^SQLi
103b0 74 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61  te will always a
103c0 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74  llocate at least
103d0 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79   mxPathname+1 by
103e0 74 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f  tes for the.** o
103f0 75 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75  utput buffer xFu
10400 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65  llPathname.  The
10410 20 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74   exact size of t
10420 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
10430 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73  .** is also pass
10440 65 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65  ed as a paramete
10450 72 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f  r to both  metho
10460 64 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75  ds. If the outpu
10470 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e  t buffer.** is n
10480 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c  ot large enough,
10490 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
104a0 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  N] should be ret
104b0 75 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69  urned. Since thi
104c0 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20  s is.** handled 
104d0 61 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72  as a fatal error
104e0 20 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20   by SQLite, vfs 
104f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
10500 73 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a  should endeavor.
10510 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68  ** to prevent th
10520 69 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78  is by setting mx
10530 50 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75  Pathname to a su
10540 66 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65  fficiently large
10550 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68   value..**.** Th
10560 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c  e xRandomness(),
10570 20 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72   xSleep(), xCurr
10580 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78  entTime(), and x
10590 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34  CurrentTimeInt64
105a0 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  ().** interfaces
105b0 20 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c   are not strictl
105c0 79 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20  y a part of the 
105d0 66 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20  filesystem, but 
105e0 74 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c  they are.** incl
105f0 75 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20  uded in the VFS 
10600 73 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f  structure for co
10610 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54  mpleteness..** T
10620 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29  he xRandomness()
10630 20 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70   function attemp
10640 74 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79  ts to return nBy
10650 74 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20  tes bytes.** of 
10660 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e  good-quality ran
10670 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75  domness into zOu
10680 74 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76  t.  The return v
10690 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61  alue is.** the a
106a0 63 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20  ctual number of 
106b0 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e  bytes of randomn
106c0 65 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a  ess obtained..**
106d0 20 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65   The xSleep() me
106e0 74 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20  thod causes the 
106f0 63 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74  calling thread t
10700 6f 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a  o sleep for at.*
10710 2a 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62  * least the numb
10720 65 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e  er of microsecon
10730 64 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20  ds given.  ^The 
10740 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a  xCurrentTime().*
10750 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  * method returns
10760 20 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75   a Julian Day Nu
10770 6d 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72  mber for the cur
10780 72 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69  rent date and ti
10790 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74  me as.** a float
107a0 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e  ing point value.
107b0 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e  .** ^The xCurren
107c0 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
107d0 68 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20  hod returns, as 
107e0 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20  an integer, the 
107f0 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75  Julian.** Day Nu
10800 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20  mber multiplied 
10810 62 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65  by 86400000 (the
10820 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69   number of milli
10830 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61  seconds in .** a
10840 20 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20   24-hour day).  
10850 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
10860 20 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e   use the xCurren
10870 74 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74  tTimeInt64() met
10880 68 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63  hod to get the c
10890 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61  urrent.** date a
108a0 6e 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20  nd time if that 
108b0 6d 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61  method is availa
108c0 62 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e  ble (if iVersion
108d0 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65   is 2 or .** gre
108e0 61 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e  ater and the fun
108f0 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
10900 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77   not NULL) and w
10910 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a  ill fall back.**
10920 20 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65   to xCurrentTime
10930 28 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69  () if xCurrentTi
10940 6d 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61  meInt64() is una
10950 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20  vailable..**.** 
10960 5e 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43  ^The xSetSystemC
10970 61 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65  all(), xGetSyste
10980 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65  mCall(), and xNe
10990 73 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69  stSystemCall() i
109a0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65  nterfaces.** are
109b0 20 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65   not used by the
109c0 20 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54   SQLite core.  T
109d0 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e  hese optional in
109e0 74 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f  terfaces are pro
109f0 76 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65  vided.** by some
10a00 20 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69   VFSes to facili
10a10 74 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20  tate testing of 
10a20 74 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79  the VFS code. By
10a30 20 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20   overriding .** 
10a40 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74  system calls wit
10a50 68 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65  h functions unde
10a60 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61  r its control, a
10a70 20 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61   test program ca
10a80 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61  n.** simulate fa
10a90 75 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63  ults and error c
10aa0 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77  onditions that w
10ab0 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62  ould otherwise b
10ac0 65 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f  e difficult.** o
10ad0 72 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20  r impossible to 
10ae0 69 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74  induce.  The set
10af0 20 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73   of system calls
10b00 20 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65   that can be ove
10b10 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65  rridden.** varie
10b20 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74  s from one VFS t
10b30 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66  o another, and f
10b40 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20  rom one version 
10b50 6f 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20  of the same VFS 
10b60 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20  to the.** next. 
10b70 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   Applications th
10b80 61 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74  at use these int
10b90 65 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20  erfaces must be 
10ba0 70 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79  prepared for any
10bb0 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68  .** or all of th
10bc0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74  ese interfaces t
10bd0 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72  o be NULL or for
10be0 20 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20   their behavior 
10bf0 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f  to change.** fro
10c00 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f  m one release to
10c10 20 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c   the next.  Appl
10c20 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f  ications must no
10c30 74 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63  t attempt to acc
10c40 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68  ess.** any of th
10c50 65 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74  ese methods if t
10c60 68 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74  he iVersion of t
10c70 68 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74  he VFS is less t
10c80 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65  han 3..*/.typede
10c90 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
10ca0 5f 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73  _vfs sqlite3_vfs
10cb0 3b 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28  ;.typedef void (
10cc0 2a 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c  *sqlite3_syscall
10cd0 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72  _ptr)(void);.str
10ce0 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20  uct sqlite3_vfs 
10cf0 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e  {.  int iVersion
10d00 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
10d10 53 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f  Structure versio
10d20 6e 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e  n number (curren
10d30 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20  tly 3) */.  int 
10d40 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20  szOsFile;       
10d50 20 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20       /* Size of 
10d60 73 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74  subclassed sqlit
10d70 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74  e3_file */.  int
10d80 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20   mxPathname;    
10d90 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
10da0 20 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c   file pathname l
10db0 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74  ength */.  sqlit
10dc0 65 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20  e3_vfs *pNext;  
10dd0 20 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69      /* Next regi
10de0 73 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20  stered VFS */.  
10df0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
10e00 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  e;       /* Name
10e10 20 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c   of this virtual
10e20 20 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a   file system */.
10e30 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
10e40 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f  ;          /* Po
10e50 69 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61  inter to applica
10e60 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61  tion-specific da
10e70 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f  ta */.  int (*xO
10e80 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73  pen)(sqlite3_vfs
10e90 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
10ea0 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69  Name, sqlite3_fi
10eb0 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20  le*,.           
10ec0 20 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69      int flags, i
10ed0 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a  nt *pOutFlags);.
10ee0 20 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29    int (*xDelete)
10ef0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10f00 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10f10 2c 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a  , int syncDir);.
10f20 20 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29    int (*xAccess)
10f30 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10f40 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
10f50 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74  , int flags, int
10f60 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e   *pResOut);.  in
10f70 74 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d  t (*xFullPathnam
10f80 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
10f90 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
10fa0 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68  me, int nOut, ch
10fb0 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69  ar *zOut);.  voi
10fc0 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71  d *(*xDlOpen)(sq
10fd0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
10fe0 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
10ff0 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  e);.  void (*xDl
11000 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76  Error)(sqlite3_v
11010 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20  fs*, int nByte, 
11020 63 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a  char *zErrMsg);.
11030 20 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79    void (*(*xDlSy
11040 6d 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  m)(sqlite3_vfs*,
11050 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61  void*, const cha
11060 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69  r *zSymbol))(voi
11070 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c  d);.  void (*xDl
11080 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76  Close)(sqlite3_v
11090 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69  fs*, void*);.  i
110a0 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73  nt (*xRandomness
110b0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
110c0 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20  int nByte, char 
110d0 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  *zOut);.  int (*
110e0 78 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f  xSleep)(sqlite3_
110f0 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73  vfs*, int micros
11100 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28  econds);.  int (
11110 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73  *xCurrentTime)(s
11120 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75  qlite3_vfs*, dou
11130 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  ble*);.  int (*x
11140 47 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71  GetLastError)(sq
11150 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c  lite3_vfs*, int,
11160 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20   char *);.  /*. 
11170 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
11180 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
11190 73 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71  sion 1 of the sq
111a0 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a  lite_vfs object.
111b0 20 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e    ** definition.
111c0 20 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c    Those that fol
111d0 6c 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e  low are added in
111e0 20 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61   version 2 or la
111f0 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  ter.  */.  int (
11200 2a 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74  *xCurrentTimeInt
11210 36 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  64)(sqlite3_vfs*
11220 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a  , sqlite3_int64*
11230 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65  );.  /*.  ** The
11240 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   methods above a
11250 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31  re in versions 1
11260 20 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71   and 2 of the sq
11270 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e  lite_vfs object.
11280 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f  .  ** Those belo
11290 77 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f  w are for versio
112a0 6e 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e  n 3 and greater.
112b0 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  .  */.  int (*xS
112c0 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71  etSystemCall)(sq
112d0 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73  lite3_vfs*, cons
112e0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73  t char *zName, s
112f0 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
11300 74 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73  tr);.  sqlite3_s
11310 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65  yscall_ptr (*xGe
11320 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
11330 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
11340 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20   char *zName);. 
11350 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78   const char *(*x
11360 4e 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  NextSystemCall)(
11370 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
11380 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
11390 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
113a0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
113b0 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
113c0 74 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65  through 3 of the
113d0 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
113e0 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65  ct..  ** New fie
113f0 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e  lds may be appen
11400 64 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65  ded in figure ve
11410 72 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65  rsions.  The iVe
11420 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65  rsion.  ** value
11430 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20   will increment 
11440 77 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61  whenever this ha
11450 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a  ppens. .  */.};.
11460 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
11470 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78   Flags for the x
11480 41 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f  Access VFS metho
11490 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
114a0 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
114b0 63 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74  can be used as t
114c0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
114d0 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63  er to.** the xAc
114e0 63 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61  cess method of a
114f0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  n [sqlite3_vfs] 
11500 6f 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65  object.  They de
11510 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20  termine.** what 
11520 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69  kind of permissi
11530 6f 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20  ons the xAccess 
11540 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e  method is lookin
11550 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53  g for..** With S
11560 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
11570 53 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73  STS, the xAccess
11580 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c   method.** simpl
11590 79 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72  y checks whether
115a0 20 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73   the file exists
115b0 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45  ..** With SQLITE
115c0 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
115d0 45 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  E, the xAccess m
115e0 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
115f0 77 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65  whether the name
11600 64 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62  d directory is b
11610 6f 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64  oth readable and
11620 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e   writable.** (in
11630 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66   other words, if
11640 20 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64   files can be ad
11650 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e  ded, removed, an
11660 64 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e  d renamed within
11670 0a 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72  .** the director
11680 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  y)..** The SQLIT
11690 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
116a0 54 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63  TE constant is c
116b0 75 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e  urrently used on
116c0 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65  ly by the.** [te
116d0 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
116e0 72 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75  ry pragma], thou
116f0 67 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68  gh this could ch
11700 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65  ange in a future
11710 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53  .** release of S
11720 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53  QLite..** With S
11730 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
11740 44 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  D, the xAccess m
11750 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20  ethod.** checks 
11760 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65  whether the file
11770 20 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54   is readable.  T
11780 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
11790 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69  _READ constant i
117a0 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75  s.** currently u
117b0 6e 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74  nused, though it
117c0 20 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69   might be used i
117d0 6e 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61  n a future relea
117e0 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e  se of.** SQLite.
117f0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
11800 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53  TE_ACCESS_EXISTS
11810 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
11820 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
11830 57 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65  WRITE 1   /* Use
11840 64 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70  d by PRAGMA temp
11850 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
11860 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11870 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20  TE_ACCESS_READ  
11880 20 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65      2   /* Unuse
11890 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d */../*.** CAPI
118a0 33 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20  3REF: Flags for 
118b0 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53  the xShmLock VFS
118c0 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68   method.**.** Th
118d0 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73  ese integer cons
118e0 74 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65  tants define the
118f0 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67   various locking
11900 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
11910 6c 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53  llowed by the xS
11920 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66  hmLock method of
11930 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
11940 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66  hods].  The.** f
11950 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65  ollowing are the
11960 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62   only legal comb
11970 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67  inations of flag
11980 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d  s to the.** xShm
11990 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a  Lock method:.**.
119a0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
119b0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
119c0 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48   | SQLITE_SHM_SH
119d0 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  ARED.** <li>  SQ
119e0 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20  LITE_SHM_LOCK | 
119f0 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
11a00 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51  SIVE.** <li>  SQ
11a10 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
11a20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
11a30 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
11a40 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
11a50 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c   SQLITE_SHM_EXCL
11a60 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  USIVE.** </ul>.*
11a70 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b  *.** When unlock
11a80 69 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48  ing, the same SH
11a90 41 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56  ARED or EXCLUSIV
11aa0 45 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73  E flag must be s
11ab0 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61  upplied as.** wa
11ac0 73 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63  s given no the c
11ad0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63  orresponding loc
11ae0 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  k.  .**.** The x
11af0 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63  ShmLock method c
11b00 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  an transition be
11b10 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61  tween unlocked a
11b20 6e 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20  nd SHARED or.** 
11b30 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64  between unlocked
11b40 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20   and EXCLUSIVE. 
11b50 20 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73   It cannot trans
11b60 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48  ition between SH
11b70 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c  ARED.** and EXCL
11b80 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e  USIVE..*/.#defin
11b90 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c  e SQLITE_SHM_UNL
11ba0 4f 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66  OCK       1.#def
11bb0 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  ine SQLITE_SHM_L
11bc0 4f 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64  OCK         2.#d
11bd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
11be0 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a  _SHARED       4.
11bf0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
11c00 48 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  HM_EXCLUSIVE    
11c10 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  8../*.** CAPI3RE
11c20 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c  F: Maximum xShmL
11c30 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20  ock index.**.** 
11c40 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  The xShmLock met
11c50 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f  hod on [sqlite3_
11c60 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20  io_methods] may 
11c70 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65  use values.** be
11c80 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73  tween 0 and this
11c90 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20   upper bound as 
11ca0 69 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67  its "offset" arg
11cb0 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51  ument..** The SQ
11cc0 4c 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e  Lite core will n
11cd0 65 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20  ever attempt to 
11ce0 61 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61  acquire or relea
11cf0 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74  se a.** lock out
11d00 73 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e  side of this ran
11d10 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge.*/.#define SQ
11d20 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20  LITE_SHM_NLOCK  
11d30 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20        8.../*.** 
11d40 43 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61  CAPI3REF: Initia
11d50 6c 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20  lize The SQLite 
11d60 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  Library.**.** ^T
11d70 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
11d80 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
11d90 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a  initializes the.
11da0 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  ** SQLite librar
11db0 79 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  y.  ^The sqlite3
11dc0 5f 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74  _shutdown() rout
11dd0 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74  ine.** deallocat
11de0 65 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  es any resources
11df0 20 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63   that were alloc
11e00 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
11e10 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a  initialize()..**
11e20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
11e30 61 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20  are designed to 
11e40 61 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69  aid in process i
11e50 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
11e60 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e  d.** shutdown on
11e70 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d   embedded system
11e80 73 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20  s.  Workstation 
11e90 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69  applications usi
11ea0 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72  ng.** SQLite nor
11eb0 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65  mally do not nee
11ec0 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68  d to invoke eith
11ed0 65 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  er of these rout
11ee0 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ines..**.** A ca
11ef0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
11f00 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e  itialize() is an
11f10 20 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c   "effective" cal
11f20 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68  l if it is.** th
11f30 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c  e first time sql
11f40 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11f50 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72  ) is invoked dur
11f60 69 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65  ing the lifetime
11f70 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65   of.** the proce
11f80 73 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20  ss, or if it is 
11f90 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73  the first time s
11fa0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
11fb0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
11fc0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61  * following a ca
11fd0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
11fe0 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c  utdown().  ^(Onl
11ff0 79 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63  y an effective c
12000 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65  all.** of sqlite
12010 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
12020 6f 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69  oes any initiali
12030 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68  zation.  All oth
12040 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20  er calls.** are 
12050 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
12060 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20  )^.**.** A call 
12070 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
12080 6f 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66  own() is an "eff
12090 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20  ective" call if 
120a0 69 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a  it is the first.
120b0 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ** call to sqlit
120c0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69  e3_shutdown() si
120d0 6e 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c  nce the last sql
120e0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
120f0 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e  ).  ^(Only.** an
12100 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20   effective call 
12110 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
12120 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64  own() does any d
12130 65 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e  einitialization.
12140 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61  .** All other va
12150 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  lid calls to sql
12160 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
12170 61 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  are harmless no-
12180 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ops.)^.**.** The
12190 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
121a0 69 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ize() interface 
121b0 69 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62  is threadsafe, b
121c0 75 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ut sqlite3_shutd
121d0 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e  own().** is not.
121e0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68    The sqlite3_sh
121f0 75 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61  utdown() interfa
12200 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20  ce must only be 
12210 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  called from a.**
12220 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
12230 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62   All open [datab
12240 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
12250 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20   must be closed 
12260 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72  and all.** other
12270 20 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65   SQLite resource
12280 73 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f  s must be deallo
12290 63 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69  cated prior to i
122a0 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  nvoking.** sqlit
122b0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  e3_shutdown()..*
122c0 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72  *.** Among other
122d0 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65   things, ^sqlite
122e0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77  3_initialize() w
122f0 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71  ill invoke.** sq
12300 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e  lite3_os_init().
12310 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71    Similarly, ^sq
12320 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12330 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20  .** will invoke 
12340 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
12350 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
12360 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12370 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ) routine return
12380 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e  s [SQLITE_OK] on
12390 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66   success..** ^If
123a0 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e   for some reason
123b0 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  , sqlite3_initia
123c0 6c 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65  lize() is unable
123d0 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a   to initialize.*
123e0 2a 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70  * the library (p
123f0 65 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61  erhaps it is una
12400 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
12410 61 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63  a needed resourc
12420 65 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d  e such.** as a m
12430 75 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73  utex) it returns
12440 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
12450 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c   other than [SQL
12460 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
12470 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
12480 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65  ialize() routine
12490 20 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72   is called inter
124a0 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74  nally by many ot
124b0 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e  her.** SQLite in
124c0 74 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74  terfaces so that
124d0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
124e0 75 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74  usually does not
124f0 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f   need to.** invo
12500 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  ke sqlite3_initi
12510 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79  alize() directly
12520 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  .  For example, 
12530 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
12540 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65  .** calls sqlite
12550 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73  3_initialize() s
12560 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
12570 72 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74  rary will be aut
12580 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e  omatically.** in
12590 69 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b  itialized when [
125a0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20  sqlite3_open()] 
125b0 69 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20  is called if it 
125c0 68 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69  has not be initi
125d0 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64  alized.** alread
125e0 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66  y.  ^However, if
125f0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
12600 6c 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51  led with the [SQ
12610 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e  LITE_OMIT_AUTOIN
12620 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74  IT].** compile-t
12630 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  ime option, then
12640 20 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63   the automatic c
12650 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
12660 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
12670 61 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20  are omitted and 
12680 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
12690 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65  must call sqlite
126a0 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64  3_initialize() d
126b0 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72  irectly.** prior
126c0 20 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74   to using any ot
126d0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
126e0 66 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d  face.  For maxim
126f0 75 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a  um portability,.
12700 2a 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** it is recomme
12710 6e 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63  nded that applic
12720 61 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e  ations always in
12730 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  voke sqlite3_ini
12740 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72  tialize().** dir
12750 65 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75  ectly prior to u
12760 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53  sing any other S
12770 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
12780 20 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65    Future release
12790 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d  s.** of SQLite m
127a0 61 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e  ay require this.
127b0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
127c0 2c 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65  , the behavior e
127d0 78 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e  xhibited.** when
127e0 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
127f0 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
12800 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20  _OMIT_AUTOINIT] 
12810 6d 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65  might become the
12820 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61  .** default beha
12830 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74  vior in some fut
12840 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53  ure release of S
12850 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
12860 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
12870 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20  () routine does 
12880 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
12890 20 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69   specific.** ini
128a0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74  tialization of t
128b0 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
128c0 79 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f  y.  The sqlite3_
128d0 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74  os_end().** rout
128e0 69 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65  ine undoes the e
128f0 66 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33  ffect of sqlite3
12900 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70  _os_init().  Typ
12910 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65  ical tasks.** pe
12920 72 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65  rformed by these
12930 20 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64   routines includ
12940 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20  e allocation or 
12950 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  deallocation.** 
12960 6f 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72  of static resour
12970 63 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74  ces, initializat
12980 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61  ion of global va
12990 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74  riables,.** sett
129a0 69 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74  ing up a default
129b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d   [sqlite3_vfs] m
129c0 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e  odule, or settin
129d0 67 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c  g up.** a defaul
129e0 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  t configuration 
129f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
12a00 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  onfig()]..**.** 
12a10 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
12a20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76  should never inv
12a30 6f 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74  oke either sqlit
12a40 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20  e3_os_init().** 
12a50 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
12a60 64 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54  d() directly.  T
12a70 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
12a80 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b  hould only invok
12a90 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69  e.** sqlite3_ini
12aa0 74 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71  tialize() and sq
12ab0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12ac0 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
12ad0 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65  s_init().** inte
12ae0 72 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20  rface is called 
12af0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
12b00 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
12b10 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c  ize() and.** sql
12b20 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73  ite3_os_end() is
12b30 20 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74   called by sqlit
12b40 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20  e3_shutdown().  
12b50 41 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69  Appropriate.** i
12b60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66  mplementations f
12b70 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  or sqlite3_os_in
12b80 69 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  it() and sqlite3
12b90 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65  _os_end().** are
12ba0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
12bb0 74 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f  te when it is co
12bc0 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c  mpiled for Unix,
12bd0 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f   Windows, or OS/
12be0 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74  2..** When [cust
12bf0 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c  om builds | buil
12c00 74 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74  t for other plat
12c10 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67  forms].** (using
12c20 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f   the [SQLITE_OS_
12c30 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65  OTHER=1] compile
12c40 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29  -time.** option)
12c50 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
12c60 20 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73   must supply a s
12c70 75 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e  uitable implemen
12c80 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71  tation for.** sq
12c90 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
12ca0 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  and sqlite3_os_e
12cb0 6e 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63  nd().  An applic
12cc0 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a  ation-supplied.*
12cd0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
12ce0 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69   of sqlite3_os_i
12cf0 6e 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  nit() or sqlite3
12d00 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73  _os_end().** mus
12d10 74 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  t return [SQLITE
12d20 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
12d30 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b  and some other [
12d40 65 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e  error code] upon
12d50 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a  .** failure..*/.
12d60 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
12d70 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12d80 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  e(void);.SQLITE_
12d90 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
12da0 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a  shutdown(void);.
12db0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
12dc0 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76  qlite3_os_init(v
12dd0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
12de0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f   int sqlite3_os_
12df0 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
12e00 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
12e10 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
12e20 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
12e30 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
12e40 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
12e50 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
12e60 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
12e70 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
12e80 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
12e90 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
12ea0 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
12eb0 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
12ec0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
12ed0 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
12ee0 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
12ef0 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
12f00 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
12f10 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
12f20 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
12f30 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
12f40 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
12f50 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
12f60 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
12f70 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
12f80 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
12f90 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
12fa0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
12fb0 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
12fc0 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
12fd0 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
12fe0 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
12ff0 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
13000 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
13010 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
13020 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
13030 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
13040 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
13050 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
13060 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
13070 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
13080 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
13090 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
130a0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
130b0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
130c0 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
130d0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
130e0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
130f0 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
13100 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
13110 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
13120 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
13130 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
13140 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
13150 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
13160 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
13170 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
13180 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
13190 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
131a0 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
131b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
131c0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
131d0 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
131e0 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
131f0 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
13200 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
13210 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
13220 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
13230 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
13240 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
13250 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
13260 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
13270 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
13280 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
13290 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
132a0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
132b0 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
132c0 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
132d0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
132e0 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
132f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13300 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
13310 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
13320 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
13330 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
13340 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
13350 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
13360 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
13370 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
13380 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
13390 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
133a0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 53 51  ror code]..*/.SQ
133b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
133c0 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c  ite3_config(int,
133d0 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   ...);../*.** CA
133e0 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
133f0 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
13400 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
13410 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66   sqlite3_db_conf
13420 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ig() interface i
13430 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63  s used to make c
13440 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
13450 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61  changes to a [da
13460 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13470 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61  n].  The interfa
13480 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ce is similar to
13490 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
134a0 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68  fig()] except th
134b0 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  at the changes a
134c0 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65  pply to a single
134d0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
134e0 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69  nnection] (speci
134f0 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  fied in the firs
13500 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a  t argument)..**.
13510 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72  ** The second ar
13520 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
13530 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c  3_db_config(D,V,
13540 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20  ...)  is the.** 
13550 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  [SQLITE_DBCONFIG
13560 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e  _LOOKASIDE | con
13570 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d  figuration verb]
13580 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f   - an integer co
13590 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69  de .** that indi
135a0 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63  cates what aspec
135b0 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  t of the [databa
135c0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
135d0 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72  s being configur
135e0 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e  ed..** Subsequen
135f0 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79  t arguments vary
13600 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
13610 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
13620 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  verb..**.** ^Cal
13630 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  ls to sqlite3_db
13640 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e  _config() return
13650 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e   SQLITE_OK if an
13660 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65  d only if.** the
13670 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65   call is conside
13680 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a  red successful..
13690 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
136a0 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  t sqlite3_db_con
136b0 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  fig(sqlite3*, in
136c0 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  t op, ...);../*.
136d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
136e0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52  ory Allocation R
136f0 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e  outines.**.** An
13700 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
13710 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73  s object defines
13720 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 62   the interface b
13730 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  etween SQLite.**
13740 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d   and low-level m
13750 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13760 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
13770 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20   This object is 
13780 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65  used in only one
13790 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53 51   place in the SQ
137a0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
137b0 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20  ** A pointer to 
137c0 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  an instance of t
137d0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74 68  his object is th
137e0 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
137f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13800 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f 6e  ()] when the con
13810 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
13820 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  n is.** [SQLITE_
13830 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f  CONFIG_MALLOC] o
13840 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
13850 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a  _GETMALLOC].  .*
13860 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61 6e  * By creating an
13870 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
13880 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20  s object.** and 
13890 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73  passing it to [s
138a0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b  qlite3_config]([
138b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
138c0 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67  LLOC]).** during
138d0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
138e0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63  an application c
138f0 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c  an specify an al
13900 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d  ternative.** mem
13910 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
13920 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51 4c  ubsystem for SQL
13930 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20 61  ite to use for a
13940 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e  ll of its.** dyn
13950 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64  amic memory need
13960 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  s..**.** Note th
13970 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73 20  at SQLite comes 
13980 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62 75  with several [bu
13990 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c  ilt-in memory al
139a0 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61  locators].** tha
139b0 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79 20  t are perfectly 
139c0 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68 65  adequate for the
139d0 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61   overwhelming ma
139e0 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  jority of applic
139f0 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68  ations.** and th
13a00 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  at this object i
13a10 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f  s only useful to
13a20 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79   a tiny minority
13a30 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
13a40 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61 6c  .** with special
13a50 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ized memory allo
13a60 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d 65  cation requireme
13a70 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  nts.  This objec
13a80 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65  t is.** also use
13a90 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e 67  d during testing
13aa0 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f 72   of SQLite in or
13ab0 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  der to specify a
13ac0 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
13ad0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13ae0 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65 73  r that simulates
13af0 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d   memory out-of-m
13b00 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73  emory conditions
13b10 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20   in.** order to 
13b20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c 69  verify that SQLi
13b30 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61 63  te recovers grac
13b40 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68  efully from such
13b50 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a  .** conditions..
13b60 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f  **.** The xMallo
13b70 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64  c, xRealloc, and
13b80 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d   xFree methods m
13b90 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68  ust work like th
13ba0 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72  e.** malloc(), r
13bb0 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  ealloc() and fre
13bc0 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72  e() functions fr
13bd0 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64 20  om the standard 
13be0 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53  C library..** ^S
13bf0 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
13c00 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e 64   that the second
13c10 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
13c20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61  xRealloc is alwa
13c30 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75 72  ys a value retur
13c40 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20 63  ned by a prior c
13c50 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e  all to xRoundup.
13c60 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f  .**.** xSize sho
13c70 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 61  uld return the a
13c80 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66  llocated size of
13c90 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
13ca0 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73  tion.** previous
13cb0 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ly obtained from
13cc0 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61   xMalloc or xRea
13cd0 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63  lloc.  The alloc
13ce0 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20  ated size.** is 
13cf0 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74 20  always at least 
13d00 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72 65  as big as the re
13d10 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75 74  quested size but
13d20 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e 0a   may be larger..
13d30 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64  **.** The xRound
13d40 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  up method return
13d50 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65 20  s what would be 
13d60 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69  the allocated si
13d70 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72  ze of.** a memor
13d80 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76  y allocation giv
13d90 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  en a particular 
13da0 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e 20  requested size. 
13db0 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20   Most memory.** 
13dc0 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64  allocators round
13dd0 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63   up memory alloc
13de0 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74 20  ations at least 
13df0 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c 74  to the next mult
13e00 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53  iple.** of 8.  S
13e10 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72  ome allocators r
13e20 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61 72  ound up to a lar
13e30 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20  ger multiple or 
13e40 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32 2e  to a power of 2.
13e50 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72 79  .** Every memory
13e60 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75   allocation requ
13e70 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68  est coming in th
13e80 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d  rough [sqlite3_m
13e90 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b  alloc()].** or [
13ea0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
13eb0 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20 78  )] first calls x
13ec0 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52 6f  Roundup.  If xRo
13ed0 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30 2c  undup returns 0,
13ee0 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65 73   .** that causes
13ef0 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
13f00 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ng memory alloca
13f10 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a  tion to fail..**
13f20 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d 65  .** The xInit me
13f30 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65 73  thod initializes
13f40 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
13f50 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78 61  cator.  (For exa
13f60 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
13f70 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
13f80 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
13f90 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
13fa0 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
13fb0 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
13fc0 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
13fd0 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
13fe0 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
13ff0 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
14000 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
14010 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
14020 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
14030 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
14040 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
14050 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
14060 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
14070 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
14080 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
14090 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
140a0 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
140b0 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
140c0 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
140d0 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
140e0 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
140f0 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
14100 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
14110 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
14120 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
14130 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
14140 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
14150 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
14160 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
14170 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
14180 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
14190 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
141a0 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
141b0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
141c0 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
141d0 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
141e0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
141f0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
14200 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14210 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
14220 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
14230 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
14240 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
14250 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
14260 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
14270 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
14280 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14290 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
142a0 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
142b0 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
142c0 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
142d0 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
142e0 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
142f0 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
14300 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
14310 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
14320 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
14330 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
14340 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
14350 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
14360 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
14370 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
14380 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
14390 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
143a0 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
143b0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
143c0 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
143d0 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
143e0 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
143f0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
14400 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
14410 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
14420 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
14430 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
14440 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
14450 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
14460 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
14470 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
14480 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
14490 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
144a0 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
144b0 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
144c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
144d0 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
144e0 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
144f0 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
14500 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
14510 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
14520 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
14530 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
14540 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
14550 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
14560 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
14570 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
14580 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
14590 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
145a0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
145b0 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
145c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
145d0 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
145e0 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
145f0 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
14600 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
14610 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
14620 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
14630 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
14640 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
14650 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
14660 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
14670 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
14680 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
14690 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
146a0 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
146b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
146c0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
146d0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
146e0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
146f0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
14700 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
14710 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
14720 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
14730 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
14740 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
14750 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
14760 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
14770 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
14780 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
14790 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
147a0 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
147b0 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
147c0 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
147d0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
147e0 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
147f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
14800 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
14810 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
14820 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
14830 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
14840 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
14850 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
14860 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
14870 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
14880 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
14890 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
148a0 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
148b0 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
148c0 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
148d0 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
148e0 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
148f0 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
14900 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
14910 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
14920 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
14930 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
14940 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
14950 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
14960 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
14970 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
14980 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
14990 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
149a0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
149b0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
149c0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
149d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
149e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
149f0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
14a00 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
14a10 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
14a20 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
14a30 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
14a40 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
14a50 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
14a60 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
14a70 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
14a80 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
14a90 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
14aa0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
14ab0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
14ac0 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
14ad0 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
14ae0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14af0 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
14b00 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
14b10 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
14b20 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
14b30 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
14b40 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
14b50 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
14b60 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
14b70 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
14b80 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
14b90 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
14ba0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
14bb0 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
14bc0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14bd0 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
14be0 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
14bf0 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
14c00 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
14c10 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
14c20 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
14c30 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
14c40 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
14c50 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
14c60 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
14c70 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
14c80 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
14c90 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
14ca0 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
14cb0 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
14cc0 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
14cd0 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
14ce0 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
14cf0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
14d00 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
14d10 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
14d20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
14d30 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
14d40 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
14d50 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14d60 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
14d70 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
14d80 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
14d90 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
14da0 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
14db0 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
14dc0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
14dd0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
14de0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
14df0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
14e00 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
14e10 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
14e20 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
14e30 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
14e40 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
14e50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
14e60 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
14e70 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
14e80 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
14e90 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
14ea0 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
14eb0 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
14ec0 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
14ed0 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
14ee0 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
14ef0 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
14f00 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
14f10 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
14f20 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
14f30 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
14f40 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
14f50 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
14f60 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
14f70 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
14f80 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
14f90 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
14fa0 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
14fb0 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
14fc0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
14fd0 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
14fe0 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
14ff0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
15000 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
15010 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
15020 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
15030 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
15040 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
15050 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
15060 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
15070 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
15080 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
15090 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
150a0 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
150b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
150c0 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
150d0 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
150e0 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
150f0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15100 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
15110 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
15120 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
15130 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
15140 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
15150 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
15160 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
15170 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
15180 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
15190 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
151a0 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
151b0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
151c0 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
151d0 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
151e0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
151f0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15200 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
15210 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15220 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
15230 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
15240 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
15250 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
15260 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
15270 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
15280 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
15290 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
152a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
152b0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
152c0 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
152d0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
152e0 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
152f0 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
15300 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
15310 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
15320 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
15330 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
15340 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
15350 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
15360 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
15370 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
15380 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
15390 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
153a0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
153b0 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
153c0 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
153d0 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
153e0 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
153f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15400 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
15410 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
15420 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
15430 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
15440 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15450 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
15460 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
15470 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
15480 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
15490 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
154a0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
154b0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
154c0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
154d0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
154e0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
154f0 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
15500 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
15510 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
15520 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
15530 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
15540 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
15550 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
15560 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
15570 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
15580 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
15590 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
155a0 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
155b0 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
155c0 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
155d0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
155e0 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
155f0 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15600 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
15610 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
15620 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
15630 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
15640 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
15650 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
15660 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
15670 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
15680 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
15690 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
156a0 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
156b0 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
156c0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
156d0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
156e0 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
156f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
15700 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
15710 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
15720 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
15730 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
15740 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
15750 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
15760 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
15770 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
15780 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
15790 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
157a0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
157b0 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
157c0 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
157d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
157e0 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
157f0 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
15800 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
15810 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
15820 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
15830 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
15840 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
15850 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
15860 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
15870 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
15880 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
15890 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
158a0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
158b0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
158c0 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
158d0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
158e0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
158f0 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
15900 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
15910 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
15920 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
15930 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
15940 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
15950 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
15960 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
15970 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
15980 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
15990 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
159a0 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
159b0 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
159c0 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
159d0 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
159e0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
159f0 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
15a00 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
15a10 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
15a20 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
15a30 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
15a40 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
15a50 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
15a60 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
15a70 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
15a80 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
15a90 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
15aa0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
15ab0 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
15ac0 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61  re than two scra
15ad0 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
15ae0 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
15af0 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
15b00 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65  o twice the expe
15b10 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
15b20 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a  ber of threads..
15b30 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
15b40 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20  never require a 
15b50 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
15b60 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
15b70 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
15b80 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
15b90 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  ze. ^If SQLite n
15ba0 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
15bb0 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
15bc0 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
15bd0 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
15be0 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
15bf0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
15c00 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
15c10 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
15c20 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
15c30 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
15c40 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
15c50 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
15c60 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
15c70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
15c80 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
15c90 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
15ca0 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
15cb0 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
15cc0 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
15cd0 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
15ce0 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
15cf0 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
15d00 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
15d10 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
15d20 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
15d30 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
15d40 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
15d50 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
15d60 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
15d70 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
15d80 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
15d90 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
15da0 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69  FIG_PCACHE2 opti
15db0 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
15dc0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
15dd0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
15de0 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
15df0 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
15e00 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
15e10 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
15e20 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
15e30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
15e40 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
15e50 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
15e60 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
15e70 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
15e80 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
15e90 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
15ea0 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
15eb0 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
15ec0 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
15ed0 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
15ee0 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
15ef0 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
15f00 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
15f10 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
15f20 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
15f30 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
15f40 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
15f50 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
15f60 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
15f70 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
15f80 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
15f90 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
15fa0 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
15fb0 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
15fc0 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
15fd0 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
15fe0 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
15ff0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
16000 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
16010 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
16020 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
16030 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
16040 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
16050 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
16060 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
16070 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
16080 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
16090 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
160a0 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
160b0 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
160c0 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
160d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
160e0 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
160f0 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
16100 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
16110 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
16120 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
16130 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
16140 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
16150 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
16160 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
16170 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
16180 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
16190 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
161a0 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c  _CONFIG_HEAP]] <
161b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
161c0 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
161d0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
161e0 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
161f0 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
16200 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
16210 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
16220 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
16230 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
16240 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
16250 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
16260 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
16270 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
16280 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
16290 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
162a0 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
162b0 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
162c0 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
162d0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
162e0 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
162f0 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
16300 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
16310 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
16320 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
16330 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
16340 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
16350 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
16360 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
16370 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
16380 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
16390 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
163a0 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
163b0 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
163c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
163d0 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
163e0 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
163f0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
16400 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
16410 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
16420 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
16430 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
16440 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
16450 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
16460 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
16470 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
16480 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
16490 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
164a0 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
164b0 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
164c0 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
164d0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
164e0 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
164f0 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
16500 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
16510 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
16520 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
16530 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
16540 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
16550 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
16560 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
16570 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
16580 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
16590 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
165a0 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
165b0 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
165c0 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
165d0 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
165e0 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
165f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16600 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
16610 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
16620 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
16630 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
16640 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16650 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
16660 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16670 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
16680 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
16690 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
166a0 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
166b0 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
166c0 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
166d0 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
166e0 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
166f0 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
16700 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
16710 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
16720 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
16730 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
16740 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
16750 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
16760 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
16770 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
16780 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
16790 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
167a0 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
167b0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
167c0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
167d0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
167e0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
167f0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
16800 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
16810 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
16820 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
16830 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
16840 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
16850 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
16860 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
16870 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
16880 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
16890 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
168a0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
168b0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
168c0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
168d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
168e0 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
168f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16900 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
16910 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
16920 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
16930 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
16940 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16950 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
16960 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
16970 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
16980 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
16990 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
169a0 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
169b0 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
169c0 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
169d0 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
169e0 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
169f0 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
16a00 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
16a10 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
16a20 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
16a30 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
16a40 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
16a50 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
16a60 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
16a70 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
16a80 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
16a90 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
16aa0 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
16ab0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
16ac0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
16ad0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
16ae0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
16af0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
16b00 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
16b10 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
16b20 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
16b30 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
16b40 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
16b50 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
16b60 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
16b70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
16b80 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
16b90 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
16ba0 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
16bb0 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
16bc0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
16bd0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
16be0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16bf0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
16c00 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
16c10 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
16c20 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
16c30 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
16c40 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
16c50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
16c60 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
16c70 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
16c80 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
16c90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
16ca0 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
16cb0 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
16cc0 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
16cd0 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
16ce0 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
16cf0 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
16d00 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
16d10 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
16d20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16d30 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
16d40 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
16d50 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
16d60 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
16d70 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
16d80 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
16d90 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
16da0 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
16db0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
16dc0 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
16dd0 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
16de0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
16df0 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
16e00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
16e10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
16e20 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
16e30 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
16e40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
16e50 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
16e60 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
16e70 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
16e80 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
16e90 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
16ea0 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
16eb0 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
16ec0 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74  pecifies the int
16ed0 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63  erface.** to a c
16ee0 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
16ef0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
16f00 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
16f10 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
16f20 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
16f30 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
16f40 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
16f50 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
16f60 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
16f70 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
16f80 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
16f90 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
16fa0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
16fb0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
16fc0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
16fd0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
16fe0 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
16ff0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
17000 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
17010 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
17020 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
17030 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
17040 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
17050 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
17060 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
17070 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
17080 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
17090 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
170a0 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
170b0 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
170c0 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
170d0 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
170e0 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
170f0 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
17100 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
17110 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
17120 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
17130 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
17140 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
17150 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
17160 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
17170 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
17180 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
17190 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
171a0 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
171b0 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
171c0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
171d0 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
171e0 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
171f0 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
17200 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
17210 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
17220 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
17230 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
17240 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
17250 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
17260 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
17270 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
17280 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
17290 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
172a0 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
172b0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
172c0 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
172d0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
172e0 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
172f0 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
17300 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
17310 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
17320 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
17330 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
17340 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
17350 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
17360 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
17370 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
17380 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
17390 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
173a0 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
173b0 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
173c0 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
173d0 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
173e0 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
173f0 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
17400 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
17410 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
17420 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
17430 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
17440 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
17450 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
17460 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
17470 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
17480 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
17490 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
174a0 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
174b0 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
174c0 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
174d0 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
174e0 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
174f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
17500 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  I]] <dt>SQLITE_C
17510 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64  ONFIG_URI.** <dd
17520 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  > This option ta
17530 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
17540 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
17550 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  t. If non-zero, 
17560 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64  then.** URI hand
17570 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
17580 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65   enabled. If the
17590 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65   parameter is ze
175a0 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e  ro, then URI han
175b0 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62  dling.** is glob
175c0 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e 20 49  ally disabled. I
175d0 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  f URI handling i
175e0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
175f0 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65  ed, all filename
17600 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20 5b  s.** passed to [
17610 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
17620 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
17630 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  2()], [sqlite3_o
17640 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73  pen16()] or.** s
17650 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72 74  pecified as part
17660 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d   of [ATTACH] com
17670 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72 70  mands are interp
17680 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20 72  reted as URIs, r
17690 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20  egardless.** of 
176a0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
176b0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
176c0 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65 74  URI] flag is set
176d0 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   when the databa
176e0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
176f0 20 69 73 20 6f 70 65 6e 65 64 2e 20 49 66 20 69   is opened. If i
17700 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  t is globally di
17710 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65  sabled, filename
17720 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e  s are.** only in
17730 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49  terpreted as URI
17740 73 20 69 66 20 74 68 65 20 53 51 4c 49 54 45 5f  s if the SQLITE_
17750 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20 69 73  OPEN_URI flag is
17760 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a   set when the.**
17770 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17780 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20  tion is opened. 
17790 42 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20  By default, URI 
177a0 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
177b0 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64  ally.** disabled
177c0 2e 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61  . The default va
177d0 6c 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67  lue may be chang
177e0 65 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20  ed by compiling 
177f0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  with the.** [SQL
17800 49 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d  ITE_USE_URI] sym
17810 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  bol defined..**.
17820 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
17830 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51  IG_PCACHE]] [[SQ
17840 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
17850 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53  CACHE]].** <dt>S
17860 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17870 43 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43  CHE and SQLITE_C
17880 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a  ONFIG_GETPCACHE.
17890 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70  ** <dd> These op
178a0 74 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65  tions are obsole
178b0 74 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  te and should no
178c0 74 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77  t be used by new
178d0 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61   code..** They a
178e0 72 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20  re retained for 
178f0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
17900 69 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20  ibility but are 
17910 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c  now no-ops..** <
17920 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
17930 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
17940 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f  NGLETHREAD  1  /
17950 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
17960 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
17970 55 4c 54 49 54 48 52 45 41 44 20 20 20 32 20 20  ULTITHREAD   2  
17980 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e  /* nil */.#defin
17990 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
179a0 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20  SERIALIZED    3 
179b0 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
179c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
179d0 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34  _MALLOC        4
179e0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
179f0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
17a00 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17a10 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20  IG_GETMALLOC    
17a20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   5  /* sqlite3_m
17a30 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
17a40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17a50 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20 20 20  NFIG_SCRATCH    
17a60 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     6  /* void*, 
17a70 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
17a80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
17a90 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
17aa0 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a       7  /* void*
17ab0 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
17ac0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17ad0 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20  E_CONFIG_HEAP   
17ae0 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69         8  /* voi
17af0 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69  d*, int nByte, i
17b00 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e  nt min */.#defin
17b10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17b20 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20 39 20  MEMSTATUS     9 
17b30 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23   /* boolean */.#
17b40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17b50 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20  NFIG_MUTEX      
17b60 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33    10  /* sqlite3
17b70 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20  _mutex_methods* 
17b80 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17b90 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
17ba0 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c  X     11  /* sql
17bb0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
17bc0 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f  ds* */./* previo
17bd0 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46  usly SQLITE_CONF
17be0 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32  IG_CHUNKALLOC 12
17bf0 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e   which is now un
17c00 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e  used. */ .#defin
17c10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
17c20 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20  LOOKASIDE    13 
17c30 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23   /* int int */.#
17c40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17c50 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20 20 20  NFIG_PCACHE     
17c60 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    14  /* no-op *
17c70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17c80 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
17c90 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f  E    15  /* no-o
17ca0 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
17cb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20  ITE_CONFIG_LOG  
17cc0 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78          16  /* x
17cd0 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23  Func, void* */.#
17ce0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
17cf0 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20  NFIG_URI        
17d00 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a    17  /* int */.
17d10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
17d20 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 20 20  ONFIG_PCACHE2   
17d30 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65     18  /* sqlite
17d40 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
17d50 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  2* */.#define SQ
17d60 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
17d70 43 41 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20  CACHE2   19  /* 
17d80 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d  sqlite3_pcache_m
17d90 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a  ethods2* */../*.
17da0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
17db0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
17dc0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
17dd0 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ptions.**.** The
17de0 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
17df0 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69   the available i
17e00 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61  nteger configura
17e10 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61  tion options tha
17e20 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73  t.** can be pass
17e30 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
17e40 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
17e50 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
17e60 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
17e70 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
17e80 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17e90 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
17ea0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
17eb0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
17ec0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
17ed0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
17ee0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
17ef0 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
17f00 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
17f10 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
17f20 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
17f30 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74  3_db_config()] t
17f40 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74  o make sure that
17f50 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72  .** the call wor
17f60 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69  ked.  ^The [sqli
17f70 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
17f80 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
17f90 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
17fa0 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
17fb0 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
17fc0 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
17fd0 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
17fe0 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
17ff0 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
18000 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  >.** <dt>SQLITE_
18010 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18020 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  DE</dt>.** <dd> 
18030 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
18040 65 73 20 74 68 72 65 65 20 61 64 64 69 74 69 6f  es three additio
18050 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68  nal arguments th
18060 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
18070 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20   .** [lookaside 
18080 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
18090 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
180a0 66 6f 72 20 74 68 65 20 5b 64 61 74 61 62 61 73  for the [databas
180b0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a  e connection]..*
180c0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
180d0 75 6d 65 6e 74 20 28 74 68 65 20 74 68 69 72 64  ument (the third
180e0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
180f0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
18100 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e  ()] is a.** poin
18110 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
18120 62 75 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f  buffer to use fo
18130 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  r lookaside memo
18140 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  ry..** ^The firs
18150 74 20 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72  t argument after
18160 20 74 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f   the SQLITE_DBCO
18170 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76  NFIG_LOOKASIDE v
18180 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55  erb.** may be NU
18190 4c 4c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  LL in which case
181a0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c   SQLite will all
181b0 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f  ocate the.** loo
181c0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 69 74  kaside buffer it
181d0 73 65 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69  self using [sqli
181e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e  te3_malloc()]. ^
181f0 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
18200 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69  ent is the.** si
18210 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
18220 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74  side buffer slot
18230 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20 61 72  .  ^The third ar
18240 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75  gument is the nu
18250 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73  mber of.** slots
18260 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
18270 68 65 20 62 75 66 66 65 72 20 69 6e 20 74 68 65  he buffer in the
18280 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18290 6d 75 73 74 20 62 65 20 67 72 65 61 74 65 72 20  must be greater 
182a0 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c  than.** or equal
182b0 20 74 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20   to the product 
182c0 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  of the second an
182d0 64 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  d third argument
182e0 73 2e 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a  s.  The buffer.*
182f0 2a 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65  * must be aligne
18300 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62  d to an 8-byte b
18310 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68  oundary.  ^If th
18320 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
18330 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44  t to.** SQLITE_D
18340 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18350 45 20 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69  E is not a multi
18360 70 6c 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20  ple of 8, it is 
18370 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f  internally.** ro
18380 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68  unded down to th
18390 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d  e next smaller m
183a0 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e  ultiple of 8.  ^
183b0 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  (The lookaside m
183c0 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75  emory.** configu
183d0 72 61 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74  ration for a dat
183e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
183f0 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61   can only be cha
18400 6e 67 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a  nged when that.*
18410 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
18420 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73  not currently us
18430 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ing lookaside me
18440 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65  mory, or in othe
18450 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20  r words.** when 
18460 74 68 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c  the "current val
18470 75 65 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ue" returned by.
18480 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73  ** [sqlite3_db_s
18490 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45  tatus](D,[SQLITE
184a0 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
184b0 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e  E],...) is zero.
184c0 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
184d0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
184e0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63  okaside memory c
184f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65  onfiguration whe
18500 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d  n lookaside.** m
18510 65 6d 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20  emory is in use 
18520 6c 65 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69  leaves the confi
18530 67 75 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67  guration unchang
18540 65 64 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a  ed and returns .
18550 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
18560 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c  .)^</dd>.**.** <
18570 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18580 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f  IG_ENABLE_FKEY</
18590 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
185a0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
185b0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
185c0 73 61 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63  sable the enforc
185d0 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72  ement of.** [for
185e0 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61  eign key constra
185f0 69 6e 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68  ints].  There sh
18600 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69  ould be two addi
18610 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
18620 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  ..** The first a
18630 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e  rgument is an in
18640 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20 30  teger which is 0
18650 20 74 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65   to disable FK e
18660 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70  nforcement,.** p
18670 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
18680 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  e FK enforcement
18690 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
186a0 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65  leave FK enforce
186b0 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65  ment.** unchange
186c0 64 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  d.  The second p
186d0 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f  arameter is a po
186e0 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
186f0 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a  ger into which.*
18700 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f  * is written 0 o
18710 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20  r 1 to indicate 
18720 77 68 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72  whether FK enfor
18730 63 65 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72  cement is off or
18740 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67   on.** following
18750 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65   this call.  The
18760 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18770 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20  r may be a NULL 
18780 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77  pointer, in.** w
18790 68 69 63 68 20 63 61 73 65 20 74 68 65 20 46 4b  hich case the FK
187a0 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74   enforcement set
187b0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
187c0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
187d0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
187e0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
187f0 45 5f 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a  E_TRIGGER</dt>.*
18800 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
18810 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65  ion is used to e
18820 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65  nable or disable
18830 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
18840 20 7c 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a   | triggers]..**
18850 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
18860 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
18870 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
18880 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
18890 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
188a0 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
188b0 61 62 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a  able triggers,.*
188c0 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
188d0 61 62 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72  able triggers or
188e0 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
188f0 76 65 20 74 68 65 20 73 65 74 74 69 6e 67 20 75  ve the setting u
18900 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65  nchanged..** The
18910 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
18920 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
18930 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
18940 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
18950 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
18960 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
18970 20 74 72 69 67 67 65 72 73 20 61 72 65 20 64 69   triggers are di
18980 73 61 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65  sabled or enable
18990 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  d.** following t
189a0 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
189b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
189c0 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
189d0 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
189e0 63 68 20 63 61 73 65 20 74 68 65 20 74 72 69 67  ch case the trig
189f0 67 65 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e  ger setting is n
18a00 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b  ot reported back
18a10 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f  . </dd>.**.** </
18a20 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  dl>.*/.#define S
18a30 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
18a40 4f 4f 4b 41 53 49 44 45 20 20 20 20 20 20 20 31  OOKASIDE       1
18a50 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e  001  /* void* in
18a60 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
18a70 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18a80 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20  _ENABLE_FKEY    
18a90 20 31 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e   1002  /* int in
18aa0 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t* */.#define SQ
18ab0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18ac0 41 42 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30  ABLE_TRIGGER  10
18ad0 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  03  /* int int* 
18ae0 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  */.../*.** CAPI3
18af0 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
18b00 69 73 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20  isable Extended 
18b10 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a  Result Codes.**.
18b20 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
18b30 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f  extended_result_
18b40 63 6f 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20  codes() routine 
18b50 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62  enables or disab
18b60 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65  les the.** [exte
18b70 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
18b80 73 5d 20 66 65 61 74 75 72 65 20 6f 66 20 53 51  s] feature of SQ
18b90 4c 69 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e  Lite. ^The exten
18ba0 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ded result.** co
18bb0 64 65 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  des are disabled
18bc0 20 62 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20   by default for 
18bd0 68 69 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61  historical compa
18be0 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a 53 51 4c  tibility..*/.SQL
18bf0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
18c00 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73  te3_extended_res
18c10 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65  ult_codes(sqlite
18c20 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a  3*, int onoff);.
18c30 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
18c40 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77   Last Insert Row
18c50 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65  id.**.** ^Each e
18c60 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c 69 74  ntry in an SQLit
18c70 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 75 6e  e table has a un
18c80 69 71 75 65 20 36 34 2d 62 69 74 20 73 69 67 6e  ique 64-bit sign
18c90 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65  ed.** integer ke
18ca0 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f  y called the [RO
18cb0 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20  WID | "rowid"]. 
18cc0 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20 61 6c  ^The rowid is al
18cd0 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a  ways available.*
18ce0 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c 61 72  * as an undeclar
18cf0 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20  ed column named 
18d00 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f  ROWID, OID, or _
18d10 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61  ROWID_ as long a
18d20 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73  s those.** names
18d30 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73   are not also us
18d40 65 64 20 62 79 20 65 78 70 6c 69 63 69 74 6c 79  ed by explicitly
18d50 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e   declared column
18d60 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61  s. ^If.** the ta
18d70 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e  ble has a column
18d80 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45 47 45   of type [INTEGE
18d90 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 74  R PRIMARY KEY] t
18da0 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a  hen that column.
18db0 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20 61 6c  ** is another al
18dc0 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f 77 69  ias for the rowi
18dd0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  d..**.** ^This r
18de0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
18df0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
18e00 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 2a 2a  e most recent.**
18e10 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53   successful [INS
18e20 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20 64 61  ERT] into the da
18e30 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68 65 20  tabase from the 
18e40 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
18e50 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20  tion].** in the 
18e60 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 20  first argument. 
18e70 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76   ^As of SQLite v
18e80 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 74 68  ersion 3.7.7, th
18e90 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 72  is routines.** r
18ea0 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73 74 20  ecords the last 
18eb0 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f 66 20  insert rowid of 
18ec0 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20 74 61  both ordinary ta
18ed0 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74 75 61  bles and [virtua
18ee0 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20 5e 49  l tables]..** ^I
18ef0 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20  f no successful 
18f00 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68 61 76  [INSERT]s.** hav
18f10 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64 20  e ever occurred 
18f20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61 73 65  on that database
18f30 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a 65 72   connection, zer
18f40 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  o is returned..*
18f50 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e  *.** ^(If an [IN
18f60 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74  SERT] occurs wit
18f70 68 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72  hin a trigger or
18f80 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75   within a [virtu
18f90 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74  al table].** met
18fa0 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72  hod, then this r
18fb0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75  outine will retu
18fc0 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  rn the [rowid] o
18fd0 66 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a  f the inserted.*
18fe0 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73  * row as long as
18ff0 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
19000 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
19010 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e  thod is running.
19020 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
19030 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74   trigger or virt
19040 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64  ual table method
19050 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65   ends, the value
19060 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79   returned .** by
19070 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65   this routine re
19080 76 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74  verts to what it
19090 20 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20   was before the 
190a0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
190b0 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68  al.** table meth
190c0 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a  od began.)^.**.*
190d0 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74  * ^An [INSERT] t
190e0 68 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f  hat fails due to
190f0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
19100 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61  olation is not a
19110 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
19120 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73  INSERT] and does
19130 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
19140 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
19150 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  y this.** routin
19160 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54  e.  ^Thus INSERT
19170 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54   OR FAIL, INSERT
19180 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45   OR IGNORE, INSE
19190 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a  RT OR ROLLBACK,.
191a0 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52  ** and INSERT OR
191b0 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63   ABORT make no c
191c0 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65  hanges to the re
191d0 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
191e0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68  is.** routine wh
191f0 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69  en their inserti
19200 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65  on fails.  ^(Whe
19210 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  n INSERT OR REPL
19220 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72  ACE.** encounter
19230 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76  s a constraint v
19240 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65  iolation, it doe
19250 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65  s not fail.  The
19260 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69  .** INSERT conti
19270 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69  nues to completi
19280 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e  on after deletin
19290 67 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73  g rows that caus
192a0 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72  ed.** the constr
192b0 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20  aint problem so 
192c0 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
192d0 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68  E will always ch
192e0 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75  ange.** the retu
192f0 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
19300 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a   interface.)^.**
19310 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72  .** ^For the pur
19320 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f  poses of this ro
19330 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52  utine, an [INSER
19340 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64  T] is considered
19350 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73   to.** be succes
19360 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20  sful even if it 
19370 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20  is subsequently 
19380 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a  rolled back..**.
19390 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** This function
193a0 20 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74   is accessible t
193b0 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  o SQL statements
193c0 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73   via the.** [las
193d0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
193e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
193f0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
19400 61 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f  ate thread perfo
19410 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52  rms a new [INSER
19420 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a  T] on the same.*
19430 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
19440 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20  ction while the 
19450 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
19460 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a  sert_rowid()].**
19470 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
19480 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68  ning and thus ch
19490 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69  anges the last i
194a0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a  nsert [rowid],.*
194b0 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65  * then the value
194c0 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
194d0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
194e0 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a  t_rowid()] is.**
194f0 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
19500 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75  nd might not equ
19510 61 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c  al either the ol
19520 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20  d or the new.** 
19530 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77  last insert [row
19540 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  id]..*/.SQLITE_A
19550 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
19560 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e   sqlite3_last_in
19570 73 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74  sert_rowid(sqlit
19580 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
19590 49 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65  I3REF: Count The
195a0 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20   Number Of Rows 
195b0 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e  Modified.**.** ^
195c0 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
195d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
195e0 20 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77   of database row
195f0 73 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e  s that were chan
19600 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74  ged.** or insert
19610 65 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79  ed or deleted by
19620 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
19630 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c  ly completed SQL
19640 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e   statement.** on
19650 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
19660 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
19670 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73  fied by the firs
19680 74 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  t parameter..** 
19690 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74  ^(Only changes t
196a0 68 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79  hat are directly
196b0 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
196c0 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44  e [INSERT], [UPD
196d0 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c  ATE],.** or [DEL
196e0 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61  ETE] statement a
196f0 72 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78  re counted.  Aux
19700 69 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63  iliary changes c
19710 61 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67  aused by.** trig
19720 67 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e  gers or [foreign
19730 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72   key actions] ar
19740 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e  e not counted.)^
19750 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   Use the.** [sql
19760 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
19770 65 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74  es()] function t
19780 6f 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c  o find the total
19790 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67   number of chang
197a0 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20  es.** including 
197b0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
197c0 79 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66  y triggers and f
197d0 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
197e0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67  ns..**.** ^Chang
197f0 65 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61  es to a view tha
19800 74 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20  t are simulated 
19810 62 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  by an [INSTEAD O
19820 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72  F trigger].** ar
19830 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20  e not counted.  
19840 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20  Only real table 
19850 63 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e  changes are coun
19860 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22  ted..**.** ^(A "
19870 72 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61  row change" is a
19880 20 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e   change to a sin
19890 67 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e  gle row of a sin
198a0 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75  gle table.** cau
198b0 73 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54  sed by an INSERT
198c0 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44  , DELETE, or UPD
198d0 41 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  ATE statement.  
198e0 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65  Rows that.** are
198f0 20 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65   changed as side
19900 20 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50   effects of [REP
19910 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
19920 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20   resolution,.** 
19930 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20  rollback, ABORT 
19940 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f  processing, [DRO
19950 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20  P TABLE], or by 
19960 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63  any other.** mec
19970 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63  hanisms do not c
19980 6f 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72  ount as direct r
19990 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a  ow changes.)^.**
199a0 0a 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63  .** A "trigger c
199b0 6f 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f  ontext" is a sco
199c0 70 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20  pe of execution 
199d0 74 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a  that begins and.
199e0 2a 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65  ** ends with the
199f0 20 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52   script of a [CR
19a00 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
19a10 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73  rigger]. .** Mos
19a20 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
19a30 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65   are.** evaluate
19a40 64 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79  d outside of any
19a50 20 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20   trigger.  This 
19a60 69 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65  is the "top leve
19a70 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f  l".** trigger co
19a80 6e 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69  ntext.  If a tri
19a90 67 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20  gger fires from 
19aa0 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61  the top level, a
19ab0 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20  .** new trigger 
19ac0 63 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72  context is enter
19ad0 65 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74  ed for the durat
19ae0 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a  ion of that one.
19af0 2a 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62  ** trigger.  Sub
19b00 74 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20  triggers create 
19b10 73 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20  subcontexts for 
19b20 74 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a  their duration..
19b30 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b  **.** ^Calling [
19b40 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20  sqlite3_exec()] 
19b50 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  or [sqlite3_step
19b60 28 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20  ()] recursively 
19b70 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61  does.** not crea
19b80 74 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72  te a new trigger
19b90 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
19ba0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72  ^This function r
19bb0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
19bc0 72 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20  r of direct row 
19bd0 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a  changes in the.*
19be0 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  * most recent IN
19bf0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
19c00 20 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e   DELETE statemen
19c10 74 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  t within the sam
19c20 65 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  e.** trigger con
19c30 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75  text..**.** ^Thu
19c40 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66  s, when called f
19c50 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
19c60 6c 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  l, this function
19c70 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
19c80 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
19c90 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65  s in the most re
19ca0 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
19cb0 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a  ATE, or DELETE.*
19cc0 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75  * that also occu
19cd0 72 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20  rred at the top 
19ce0 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e  level.  ^(Within
19cf0 20 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74   the body of a t
19d00 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73  rigger,.** the s
19d10 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
19d20 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
19d30 65 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64  e called to find
19d40 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
19d50 2a 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65  * changes in the
19d60 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63   most recently c
19d70 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c  ompleted INSERT,
19d80 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
19d90 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  TE.** statement 
19da0 77 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20  within the body 
19db0 6f 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67  of the same trig
19dc0 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ger..** However,
19dd0 20 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75   the number retu
19de0 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e  rned does not in
19df0 63 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a  clude changes.**
19e00 20 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72   caused by subtr
19e10 69 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f  iggers since tho
19e20 73 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77  se have their ow
19e30 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a  n context.)^.**.
19e40 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
19e50 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
19e60 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
19e70 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
19e80 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
19e90 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61  a], and the [cha
19ea0 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74  nges() SQL funct
19eb0 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  ion]..**.** If a
19ec0 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
19ed0 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f   makes changes o
19ee0 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  n the same datab
19ef0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
19f00 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33  * while [sqlite3
19f10 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
19f20 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
19f30 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
19f40 2a 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  * is unpredictab
19f50 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
19f60 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ngful..*/.SQLITE
19f70 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
19f80 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
19f90 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
19fa0 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65  REF: Total Numbe
19fb0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
19fc0 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
19fd0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
19fe0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  the number of ro
19ff0 77 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64  w changes caused
1a000 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a   by [INSERT],.**
1a010 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45   [UPDATE] or [DE
1a020 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73  LETE] statements
1a030 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61   since the [data
1a040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1a050 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20   was opened..** 
1a060 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75  ^(The count retu
1a070 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
1a080 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20  total_changes() 
1a090 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61  includes all cha
1a0a0 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c  nges.** from all
1a0b0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
1a0c0 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74   | trigger] cont
1a0d0 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73  exts and changes
1a0e0 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72   made by.** [for
1a0f0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
1a100 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74  ]. However,.** t
1a110 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f  he count does no
1a120 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
1a130 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  s used to implem
1a140 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f  ent [REPLACE] co
1a150 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f  nstraints,.** do
1a160 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42   rollbacks or AB
1a170 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
1a180 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20  or [DROP TABLE] 
1a190 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65  processing.  The
1a1a0 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e  .** count does n
1a1b0 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20  ot include rows 
1a1c0 6f 66 20 76 69 65 77 73 20 74 68 61 74 20 66 69  of views that fi
1a1d0 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f  re an [INSTEAD O
1a1e0 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74  F trigger],.** t
1a1f0 68 6f 75 67 68 20 69 66 20 74 68 65 20 49 4e 53  hough if the INS
1a200 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72 20  TEAD OF trigger 
1a210 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66  makes changes of
1a220 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20   its own, those 
1a230 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20  changes .** are 
1a240 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54  counted.)^.** ^T
1a250 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  he sqlite3_total
1a260 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74  _changes() funct
1a270 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63  ion counts the c
1a280 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61  hanges as soon a
1a290 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65  s.** the stateme
1a2a0 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68  nt that makes th
1a2b0 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20  em is completed 
1a2c0 28 77 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d  (when the statem
1a2d0 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73  ent handle.** is
1a2e0 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
1a2f0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
1a300 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
1a310 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  e()])..**.** See
1a320 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
1a330 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  e3_changes()] in
1a340 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
1a350 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
1a360 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
1a370 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29  [total_changes()
1a380 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1a390 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1a3a0 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
1a3b0 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
1a3c0 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1a3d0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
1a3e0 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  e [sqlite3_total
1a3f0 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72  _changes()] is r
1a400 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20  unning then the 
1a410 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65  value.** returne
1a420 64 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62  d is unpredictab
1a430 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69  le and not meani
1a440 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ngful..*/.SQLITE
1a450 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1a460 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73  _total_changes(s
1a470 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1a480 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72   CAPI3REF: Inter
1a490 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e  rupt A Long-Runn
1a4a0 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20  ing Query.**.** 
1a4b0 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63  ^This function c
1a4c0 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e  auses any pendin
1a4d0 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  g database opera
1a4e0 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e  tion to abort an
1a4f0 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69  d.** return at i
1a500 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f  ts earliest oppo
1a510 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f  rtunity. This ro
1a520 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c  utine is typical
1a530 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20  ly.** called in 
1a540 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73  response to a us
1a550 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61  er action such a
1a560 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63  s pressing "Canc
1a570 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43  el".** or Ctrl-C
1a580 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72 20   where the user 
1a590 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65  wants a long que
1a5a0 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20  ry operation to 
1a5b0 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74  halt.** immediat
1a5c0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  ely..**.** ^It i
1a5d0 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  s safe to call t
1a5e0 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d  his routine from
1a5f0 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65 72   a thread differ
1a600 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20  ent from the.** 
1a610 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20 63  thread that is c
1a620 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67  urrently running
1a630 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 70   the database op
1a640 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74  eration.  But it
1a650 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20  .** is not safe 
1a660 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1a670 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74  tine with a [dat
1a680 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1a690 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f  ] that.** is clo
1a6a0 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f  sed or might clo
1a6b0 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65  se before sqlite
1a6c0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72 65  3_interrupt() re
1a6d0 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  turns..**.** ^If
1a6e0 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f   an SQL operatio
1a6f0 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79  n is very nearly
1a700 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68 65   finished at the
1a710 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71   time when.** sq
1a720 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1a730 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65  ) is called, the
1a740 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68  n it might not h
1a750 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69  ave an opportuni
1a760 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65  ty.** to be inte
1a770 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68  rrupted and migh
1a780 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f  t continue to co
1a790 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  mpletion..**.** 
1a7a0 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ^An SQL operatio
1a7b0 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72 72  n that is interr
1a7c0 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72  upted will retur
1a7d0 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  n [SQLITE_INTERR
1a7e0 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  UPT]..** ^If the
1a7f0 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c   interrupted SQL
1a800 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e   operation is an
1a810 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
1a820 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68   or DELETE.** th
1a830 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20  at is inside an 
1a840 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
1a850 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65  tion, then the e
1a860 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f  ntire transactio
1a870 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c  n.** will be rol
1a880 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74  led back automat
1a890 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ically..**.** ^T
1a8a0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1a8b0 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20  rupt(D) call is 
1a8c0 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20  in effect until 
1a8d0 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75  all currently ru
1a8e0 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61  nning.** SQL sta
1a8f0 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61  tements on [data
1a900 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1a910 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41   D complete.  ^A
1a920 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65  ny new SQL state
1a930 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
1a940 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
1a950 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
1a960 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64  rrupt() call and
1a970 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20   before the .** 
1a980 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
1a990 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20  ts reaches zero 
1a9a0 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  are interrupted 
1a9b0 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20 62  as if they had b
1a9c0 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70  een.** running p
1a9d0 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69  rior to the sqli
1a9e0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
1a9f0 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20  call.  ^New SQL 
1aa00 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1aa10 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1aa20 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67  fter the running
1aa30 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74   statement count
1aa40 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
1aa50 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65  e.** not effecte
1aa60 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
1aa70 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a  _interrupt()..**
1aa80 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69   ^A call to sqli
1aa90 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1aaa0 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68 65   that occurs whe
1aab0 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72  n there are no r
1aac0 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
1aad0 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f  atements is a no
1aae0 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65  -op and has no e
1aaf0 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61  ffect on SQL sta
1ab00 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
1ab10 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
1ab20 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  r the sqlite3_in
1ab30 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72  terrupt() call r
1ab40 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66  eturns..**.** If
1ab50 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
1ab60 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20  nnection closes 
1ab70 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69  while [sqlite3_i
1ab80 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69  nterrupt()].** i
1ab90 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62  s running then b
1aba0 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c  ad things will l
1abb0 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f  ikely happen..*/
1abc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
1abd0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1abe0 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  pt(sqlite3*);../
1abf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
1ac00 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
1ac10 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20  QL Statement Is 
1ac20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54  Complete.**.** T
1ac30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
1ac40 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20  e useful during 
1ac50 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70  command-line inp
1ac60 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ut to determine 
1ac70 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e  if the.** curren
1ac80 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65 78 74  tly entered text
1ac90 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61   seems to form a
1aca0 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1acb0 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66  atement or.** if
1acc0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75   additional inpu
1acd0 74 20 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f  t is needed befo
1ace0 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74  re sending the t
1acf0 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69  ext into.** SQLi
1ad00 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20  te for parsing. 
1ad10 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1ad20 20 72 65 74 75 72 6e 20 31 20 69 66 20 74 68 65   return 1 if the
1ad30 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a   input string.**
1ad40 20 61 70 70 65 61 72 73 20 74 6f 20 62 65 20 61   appears to be a
1ad50 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74   complete SQL st
1ad60 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61  atement.  ^A sta
1ad70 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64  tement is judged
1ad80 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65   to be.** comple
1ad90 74 65 20 69 66 20 69 74 20 65 6e 64 73 20 77 69  te if it ends wi
1ada0 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74  th a semicolon t
1adb0 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20  oken and is not 
1adc0 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a  a prefix of a.**
1add0 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45   well-formed CRE
1ade0 41 54 45 20 54 52 49 47 47 45 52 20 73 74 61 74  ATE TRIGGER stat
1adf0 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c  ement.  ^Semicol
1ae00 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65 6d 62  ons that are emb
1ae10 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  edded within.** 
1ae20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20  string literals 
1ae30 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69  or quoted identi
1ae40 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f  fier names or co
1ae50 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a  mments are not.*
1ae60 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f  * independent to
1ae70 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65 20 70  kens (they are p
1ae80 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e  art of the token
1ae90 20 69 6e 20 77 68 69 63 68 20 74 68 65 79 20 61   in which they a
1aea0 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20  re.** embedded) 
1aeb0 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20  and thus do not 
1aec0 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61 74 65  count as a state
1aed0 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e  ment terminator.
1aee0 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a    ^Whitespace.**
1aef0 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68   and comments th
1af00 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69  at follow the fi
1af10 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72  nal semicolon ar
1af20 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  e ignored..**.**
1af30 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
1af40 20 72 65 74 75 72 6e 20 30 20 69 66 20 74 68 65   return 0 if the
1af50 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e   statement is in
1af60 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61  complete.  ^If a
1af70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
1af80 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65  ation fails, the
1af90 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69  n SQLITE_NOMEM i
1afa0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
1afb0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
1afc0 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74  s do not parse t
1afd0 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
1afe0 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e  s thus.** will n
1aff0 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74 61 63  ot detect syntac
1b000 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63  tically incorrec
1b010 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  t SQL..**.** ^(I
1b020 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74  f SQLite has not
1b030 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65   been initialize
1b040 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
1b050 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70  _initialize()] p
1b060 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f  rior .** to invo
1b070 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d  king sqlite3_com
1b080 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e 20 73  plete16() then s
1b090 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
1b0a0 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a  e() is invoked.*
1b0b0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
1b0c0 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  by sqlite3_compl
1b0d0 65 74 65 31 36 28 29 2e 20 20 49 66 20 74 68 61  ete16().  If tha
1b0e0 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  t initialization
1b0f0 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20   fails,.** then 
1b100 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
1b110 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
1b120 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20  mplete16() will 
1b130 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72  be non-zero.** r
1b140 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1b150 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
1b160 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d  input SQL is com
1b170 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54  plete.)^.**.** T
1b180 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c  he input to [sql
1b190 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d  ite3_complete()]
1b1a0 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d   must be a zero-
1b1b0 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
1b1c0 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  F-8 string..**.*
1b1d0 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1b1e0 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b1f0 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20  16()] must be a 
1b200 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1b210 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
1b220 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20   in native byte 
1b230 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  order..*/.SQLITE
1b240 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1b250 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20  _complete(const 
1b260 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53 51 4c 49  char *sql);.SQLI
1b270 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1b280 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
1b290 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
1b2a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1b2b0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
1b2c0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
1b2d0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
1b2e0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
1b2f0 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
1b300 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
1b310 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
1b320 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
1b330 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
1b340 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
1b350 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
1b360 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
1b370 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
1b380 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
1b390 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
1b3a0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
1b3b0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
1b3c0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
1b3d0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
1b3e0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
1b3f0 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
1b400 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
1b410 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
1b420 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
1b430 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
1b440 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
1b450 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
1b460 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
1b470 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
1b480 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
1b490 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1b4a0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
1b4b0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
1b4c0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
1b4d0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
1b4e0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
1b4f0 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
1b500 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
1b510 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
1b520 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
1b530 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
1b540 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
1b550 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
1b560 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
1b570 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
1b580 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
1b590 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
1b5a0 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
1b5b0 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
1b5c0 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
1b5d0 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
1b5e0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
1b5f0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
1b600 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
1b610 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
1b620 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
1b630 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1b640 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
1b650 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
1b660 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  ** is made to op
1b670 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
1b680 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1b690 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
1b6a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
1b6b0 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
1b6c0 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
1b6d0 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
1b6e0 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
1b6f0 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
1b700 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
1b710 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
1b720 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
1b730 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
1b740 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
1b750 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
1b760 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
1b770 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
1b780 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
1b790 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  Y].** or [SQLITE
1b7a0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
1b7b0 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
1b7c0 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
1b7d0 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
1b7e0 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
1b7f0 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
1b800 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
1b810 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
1b820 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
1b830 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
1b840 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
1b850 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
1b860 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
1b870 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
1b880 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
1b890 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
1b8a0 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
1b8b0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
1b8c0 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
1b8d0 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
1b8e0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1b8f0 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
1b900 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
1b910 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
1b920 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
1b930 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
1b940 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
1b950 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
1b960 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
1b970 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
1b980 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
1b990 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
1b9a0 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
1b9b0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
1b9c0 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
1b9d0 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
1b9e0 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
1b9f0 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
1ba00 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
1ba10 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
1ba20 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
1ba30 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
1ba40 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
1ba50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
1ba60 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
1ba70 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
1ba80 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42  * ^The [SQLITE_B
1ba90 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f  USY] error is co
1baa0 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49  nverted to [SQLI
1bab0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
1bac0 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  ].** when SQLite
1bad0 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c   is in the middl
1bae0 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61  e of a large tra
1baf0 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61  nsaction where a
1bb00 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65  ll the.** change
1bb10 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69  s will not fit i
1bb20 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  nto the in-memor
1bb30 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65  y cache.  SQLite
1bb40 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79   will.** already
1bb50 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44   hold a RESERVED
1bb60 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74   lock on the dat
1bb70 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20  abase file, but 
1bb80 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70  it needs.** to p
1bb90 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b  romote this lock
1bba0 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f   to EXCLUSIVE so
1bbb0 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69   that it can spi
1bbc0 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65  ll cache.** page
1bbd0 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  s into the datab
1bbe0 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74  ase file without
1bbf0 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72   harm to concurr
1bc00 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20  ent.** readers. 
1bc10 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c   ^If it is unabl
1bc20 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
1bc30 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
1bc40 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
1bc50 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
1bc60 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
1bc70 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
1bc80 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
1bc90 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
1bca0 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
1bcb0 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
1bcc0 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
1bcd0 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
1bce0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
1bcf0 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f  ED].  ^This erro
1bd00 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
1bd10 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
1bd20 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
1bd30 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
1bd40 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
1bd50 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77  href="/cvstrac/w
1bd60 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
1bd70 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
1bd80 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
1bd90 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
1bda0 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
1bdb0 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
1bdc0 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
1bdd0 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
1bde0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1bdf0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1be00 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1be10 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
1be20 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
1be30 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
1be40 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
1be50 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
1be60 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
1be70 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
1be80 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
1be90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
1bea0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
1beb0 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
1bec0 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20   clear the busy 
1bed0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
1bee0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1bef0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
1bf00 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
1bf10 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
1bf20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1bf30 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1bf40 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
1bf50 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  er.  Any such ac
1bf60 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
1bf70 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
1bf80 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
1bf90 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
1bfa0 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
1bfb0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1bfc0 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
1bfd0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
1bfe0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1bff0 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
1c000 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
1c010 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e  sqlite3_busy_han
1c020 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69  dler(sqlite3*, i
1c030 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29  nt(*)(void*,int)
1c040 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1c050 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20 41   CAPI3REF: Set A
1c060 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a   Busy Timeout.**
1c070 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
1c080 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74 65  e sets a [sqlite
1c090 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c  3_busy_handler |
1c0a0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20 74   busy handler] t
1c0b0 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f  hat sleeps.** fo
1c0c0 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61 6d  r a specified am
1c0d0 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68 65  ount of time whe
1c0e0 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f 63  n a table is loc
1c0f0 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c  ked.  ^The handl
1c100 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70  er.** will sleep
1c110 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
1c120 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20 22  until at least "
1c130 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73  ms" milliseconds
1c140 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20   of sleeping.** 
1c150 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65 64  have accumulated
1c160 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65 61  .  ^After at lea
1c170 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63  st "ms" millisec
1c180 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67  onds of sleeping
1c190 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65 72  ,.** the handler
1c1a0 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63 68   returns 0 which
1c1b0 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65 33   causes [sqlite3
1c1c0 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74 75  _step()] to retu
1c1d0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  rn.** [SQLITE_BU
1c1e0 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
1c1f0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a  OERR_BLOCKED]..*
1c200 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68  *.** ^Calling th
1c210 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68 20  is routine with 
1c220 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73 73  an argument less
1c230 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74   than or equal t
1c240 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20  o zero.** turns 
1c250 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61 6e  off all busy han
1c260 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  dlers..**.** ^(T
1c270 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
1c280 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
1c290 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61 72  andler for a par
1c2a0 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61  ticular.** [data
1c2b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
1c2c0 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20 6d   any any given m
1c2d0 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68  oment.  If anoth
1c2e0 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 0a  er busy handler.
1c2f0 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20 20  ** was defined  
1c300 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  (using [sqlite3_
1c310 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29  busy_handler()])
1c320 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e   prior to callin
1c330 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  g.** this routin
1c340 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62 75  e, that other bu
1c350 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63 6c  sy handler is cl
1c360 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53 51 4c 49  eared.)^.*/.SQLI
1c370 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
1c380 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1c390 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1c3a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1c3b0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1c3c0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1c3d0 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a  ning Queries.**.
1c3e0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67  ** This is a leg
1c3f0 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  acy interface th
1c400 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20  at is preserved 
1c410 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1c420 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20  mpatibility..** 
1c430 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  Use of this inte
1c440 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63  rface is not rec
1c450 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommended..**.** 
1c460 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
1c470 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
1c480 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
1c490 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
1c4a0 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
1c4b0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1c4c0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
1c4d0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
1c4e0 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
1c4f0 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
1c500 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
1c510 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
1c520 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
1c530 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
1c540 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1c550 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
1c560 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
1c570 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
1c580 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1c590 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
1c5a0 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
1c5b0 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
1c5c0 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
1c5d0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1c5e0 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
1c5f0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1c600 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
1c610 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
1c620 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
1c630 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
1c640 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1c650 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
1c660 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
1c670 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
1c680 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
1c690 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
1c6a0 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1c6b0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1c6c0 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
1c6d0 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
1c6e0 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
1c6f0 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
1c700 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
1c710 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
1c720 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
1c730 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
1c740 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
1c750 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
1c760 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
1c770 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1c780 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
1c790 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
1c7a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1c7b0 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
1c7c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
1c7d0 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
1c7e0 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
1c7f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
1c800 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
1c810 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
1c820 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
1c830 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1c840 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
1c850 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
1c860 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
1c870 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
1c880 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
1c890 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65   ^(As an example
1c8a0 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1c8b0 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
1c8c0 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
1c8d0 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
1c8e0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1c8f0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1c900 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
1c910 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
1c920 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
1c930 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
1c940 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
1c950 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
1c960 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
1c970 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
1c980 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
1c990 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1c9a0 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
1c9b0 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
1c9c0 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
1c9d0 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
1c9e0 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
1c9f0 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
1ca00 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
1ca10 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1ca20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
1ca30 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
1ca40 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
1ca50 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
1ca60 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
1ca70 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1ca80 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
1ca90 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
1caa0 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
1cab0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
1cac0 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
1cad0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1cae0 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
1caf0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1cb00 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
1cb10 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1cb20 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
1cb30 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
1cb40 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
1cb50 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
1cb60 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
1cb70 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
1cb80 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1cb90 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
1cba0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1cbb0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1cbc0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1cbd0 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
1cbe0 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
1cbf0 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
1cc00 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
1cc10 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
1cc20 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1cc30 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
1cc40 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
1cc50 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
1cc60 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
1cc70 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
1cc80 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
1cc90 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
1cca0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
1ccb0 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20  application has 
1ccc0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
1ccd0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71  e result from sq
1cce0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1ccf0 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61  ),.** it must pa
1cd00 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ss the result ta
1cd10 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ble pointer to s
1cd20 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1cd30 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
1cd40 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
1cd50 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
1cd60 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
1cd70 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
1cd80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
1cd90 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
1cda0 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
1cdb0 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
1cdc0 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
1cdd0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
1cde0 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
1cdf0 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
1ce00 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
1ce10 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1ce20 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
1ce30 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1ce40 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
1ce50 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
1ce60 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1ce70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
1ce80 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
1ce90 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
1cea0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1ceb0 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
1cec0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
1ced0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
1cee0 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
1cef0 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
1cf00 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
1cf10 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
1cf20 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
1cf30 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
1cf40 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
1cf50 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
1cf60 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
1cf70 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
1cf80 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
1cf90 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
1cfa0 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
1cfb0 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
1cfc0 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
1cfd0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
1cfe0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
1cff0 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
1d000 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1d010 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
1d020 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74   int sqlite3_get
1d030 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65  _table(.  sqlite
1d040 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
1d050 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62  /* An open datab
1d060 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  ase */.  const c
1d070 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f  har *zSql,     /
1d080 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c  * SQL to be eval
1d090 75 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20  uated */.  char 
1d0a0 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20  ***pazResult,   
1d0b0 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74   /* Results of t
1d0c0 68 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e  he query */.  in
1d0d0 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20  t *pnRow,       
1d0e0 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
1d0f0 20 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69   result rows wri
1d100 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69  tten here */.  i
1d110 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20  nt *pnColumn,   
1d120 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f       /* Number o
1d130 66 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73  f result columns
1d140 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
1d150 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d  .  char **pzErrm
1d160 73 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f  sg       /* Erro
1d170 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
1d180 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  re */.);.SQLITE_
1d190 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
1d1a0 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
1d1b0 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
1d1c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
1d1d0 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
1d1e0 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
1d1f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
1d200 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
1d210 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
1d220 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
1d230 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
1d240 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
1d250 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
1d260 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1d270 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
1d280 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
1d290 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
1d2a0 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
1d2b0 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
1d2c0 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
1d2d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
1d2e0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
1d2f0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
1d300 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
1d310 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
1d320 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
1d330 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
1d340 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
1d350 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
1d360 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
1d370 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
1d380 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
1d390 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
1d3a0 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
1d3b0 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
1d3c0 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
1d3d0 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
1d3e0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
1d3f0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
1d400 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
1d410 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
1d420 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
1d430 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
1d440 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
1d450 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
1d460 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
1d470 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
1d480 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
1d490 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
1d4a0 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
1d4b0 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
1d4c0 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
1d4d0 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
1d4e0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
1d4f0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
1d500 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
1d510 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
1d520 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1d530 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
1d540 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
1d550 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
1d560 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1d570 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
1d580 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
1d590 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
1d5a0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
1d5b0 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
1d5c0 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
1d5d0 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
1d5e0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
1d5f0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
1d600 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
1d610 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
1d620 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
1d630 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
1d640 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
1d650 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
1d660 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
1d670 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
1d680 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
1d690 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1d6a0 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
1d6b0 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
1d6c0 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
1d6d0 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
1d6e0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
1d6f0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
1d700 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
1d710 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
1d720 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
1d730 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
1d740 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
1d750 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
1d760 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
1d770 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
1d780 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
1d790 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
1d7a0 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
1d7b0 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
1d7c0 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
1d7d0 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
1d7e0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d7f0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
1d800 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
1d810 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
1d820 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
1d830 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
1d840 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
1d850 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
1d860 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
1d870 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
1d880 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
1d890 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
1d8a0 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
1d8b0 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
1d8c0 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
1d8d0 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
1d8e0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
1d8f0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
1d900 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
1d910 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
1d920 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
1d930 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1d940 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
1d950 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 2d  bstitutes a nul-
1d960 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74  terminated.** st
1d970 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61 72  ring from the ar
1d980 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42 75  gument list.  Bu
1d990 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65  t %q also double
1d9a0 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68 61  s every '\'' cha
1d9b0 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73  racter..** %q is
1d9c0 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75 73   designed for us
1d9d0 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69 6e  e inside a strin
1d9e0 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42 79  g literal.)^  By
1d9f0 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20 27   doubling each '
1da00 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65 72  \''.** character
1da10 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61 74   it escapes that
1da20 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20 61   character and a
1da30 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20 69  llows it to be i
1da40 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20  nserted into.** 
1da50 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  the string..**.*
1da60 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61  * For example, a
1da70 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e 67  ssume the string
1da80 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74 20   variable zText 
1da90 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61 73  contains text as
1daa0 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20   follows:.**.** 
1dab0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1dac0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65 78  >.**  char *zTex
1dad0 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70 70  t = "It's a happ
1dae0 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72  y day!";.** </pr
1daf0 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
1db00 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73  **.** One can us
1db10 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20 61  e this text in a
1db20 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  n SQL statement 
1db30 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
1db40 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1db50 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53  re>.**  char *zS
1db60 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72  QL = sqlite3_mpr
1db70 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54  intf("INSERT INT
1db80 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28 27  O table VALUES('
1db90 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a  %q')", zText);.*
1dba0 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  *  sqlite3_exec(
1dbb0 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20  db, zSQL, 0, 0, 
1dbc0 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  0);.**  sqlite3_
1dbd0 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c  free(zSQL);.** <
1dbe0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1dbf0 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65  e>.**.** Because
1dc00 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20 73   the %q format s
1dc10 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  tring is used, t
1dc20 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74 65  he '\'' characte
1dc30 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73  r in zText.** is
1dc40 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68 65   escaped and the
1dc50 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20 69   SQL generated i
1dc60 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  s as follows:.**
1dc70 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
1dc80 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54  <pre>.**  INSERT
1dc90 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c   INTO table1 VAL
1dca0 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61 70  UES('It''s a hap
1dcb0 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70  py day!').** </p
1dcc0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1dcd0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 63  .**.** This is c
1dce0 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65 20  orrect.  Had we 
1dcf0 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64 20  used %s instead 
1dd00 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65 72  of %q, the gener
1dd10 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c  ated SQL.** woul
1dd20 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69  d have looked li
1dd30 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ke this:.**.** <
1dd40 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1dd50 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f  .**  INSERT INTO
1dd60 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27   table1 VALUES('
1dd70 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79  It's a happy day
1dd80 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  !');.** </pre></
1dd90 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1dda0 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65 78  * This second ex
1ddb0 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c 20  ample is an SQL 
1ddc0 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20 41  syntax error.  A
1ddd0 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c 65  s a general rule
1dde0 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61   you should.** a
1ddf0 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e 73  lways use %q ins
1de00 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e 20  tead of %s when 
1de10 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20 69  inserting text i
1de20 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69 74  nto a string lit
1de30 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  eral..**.** ^(Th
1de40 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b  e %Q option work
1de50 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70 74  s like %q except
1de60 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73 69   it also adds si
1de70 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f 75  ngle quotes arou
1de80 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69 64  nd.** the outsid
1de90 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20 73  e of the total s
1dea0 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e  tring.  Addition
1deb0 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61 72  ally, if the par
1dec0 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a  ameter in the.**
1ded0 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20 69   argument list i
1dee0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1def0 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65 73  , %Q substitutes
1df00 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c 22   the text "NULL"
1df10 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e   (without.** sin
1df20 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20 20  gle quotes).)^  
1df30 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  So, for example,
1df40 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a   one could say:.
1df50 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1df60 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
1df70 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
1df80 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
1df90 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
1dfa0 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29 3b  ES(%Q)", zText);
1dfb0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65  .**  sqlite3_exe
1dfc0 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30  c(db, zSQL, 0, 0
1dfd0 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65  , 0);.**  sqlite
1dfe0 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a  3_free(zSQL);.**
1dff0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1e000 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ote>.**.** The c
1e010 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20 72  ode above will r
1e020 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74 20  ender a correct 
1e030 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1e040 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72   the zSQL.** var
1e050 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74 68  iable even if th
1e060 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c 65  e zText variable
1e070 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
1e080 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  er..**.** ^(The 
1e090 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67 20  "%z" formatting 
1e0a0 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b  option works lik
1e0b0 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68 20  e "%s" but with 
1e0c0 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20  the.** addition 
1e0d0 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20 73  that after the s
1e0e0 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20 72  tring has been r
1e0f0 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20 69  ead and copied i
1e100 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c  nto.** the resul
1e110 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  t, [sqlite3_free
1e120 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  ()] is called on
1e130 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e   the input strin
1e140 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  g.)^.*/.SQLITE_A
1e150 50 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  PI char *sqlite3
1e160 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63  _mprintf(const c
1e170 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51 4c 49 54  har*,...);.SQLIT
1e180 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1e190 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e  te3_vmprintf(con
1e1a0 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73  st char*, va_lis
1e1b0 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
1e1c0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
1e1d0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1e1e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1e1f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68  );.SQLITE_API ch
1e200 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70  ar *sqlite3_vsnp
1e210 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1e220 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1e230 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  list);../*.** CA
1e240 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41  PI3REF: Memory A
1e250 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73  llocation Subsys
1e260 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  tem.**.** The SQ
1e270 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20 74  Lite core uses t
1e280 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74 69  hese three routi
1e290 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69  nes for all of i
1e2a0 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e  ts own.** intern
1e2b0 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  al memory alloca
1e2c0 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72  tion needs. "Cor
1e2d0 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f  e" in the previo
1e2e0 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64  us sentence.** d
1e2f0 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1e300 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d  operating-system
1e310 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69 6d   specific VFS im
1e320 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54  plementation.  T
1e330 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46  he.** Windows VF
1e340 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61  S uses native ma
1e350 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
1e360 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61  ) for some opera
1e370 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions..**.** ^Th
1e380 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  e sqlite3_malloc
1e390 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
1e3a0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1e3b0 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65  a block.** of me
1e3c0 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20  mory at least N 
1e3d0 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c  bytes in length,
1e3e0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
1e3f0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49  parameter..** ^I
1e400 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
1e410 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
1e420 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e  obtain sufficien
1e430 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79  t free.** memory
1e440 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e  , it returns a N
1e450 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49  ULL pointer.  ^I
1e460 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1e470 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  N to.** sqlite3_
1e480 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f  malloc() is zero
1e490 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68 65   or negative the
1e4a0 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  n sqlite3_malloc
1e4b0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  () returns.** a 
1e4c0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1e4d0 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c  .** ^Calling sql
1e4e0 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74 68  ite3_free() with
1e4f0 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69   a pointer previ
1e500 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a  ously returned.*
1e510 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  * by sqlite3_mal
1e520 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33  loc() or sqlite3
1e530 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61  _realloc() relea
1e540 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  ses that memory 
1e550 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69  so.** that it mi
1e560 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20 20  ght be reused.  
1e570 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65  ^The sqlite3_fre
1e580 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a  e() routine is.*
1e590 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20  * a no-op if is 
1e5a0 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55  called with a NU
1e5b0 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73  LL pointer.  Pas
1e5c0 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  sing a NULL poin
1e5d0 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65  ter.** to sqlite
1e5e0 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72 6d  3_free() is harm
1e5f0 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65 69  less.  After bei
1e600 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79  ng freed, memory
1e610 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68  .** should neith
1e620 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77  er be read nor w
1e630 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65  ritten.  Even re
1e640 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79  ading previously
1e650 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79   freed.** memory
1e660 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e   might result in
1e670 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1e680 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73  fault or other s
1e690 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  evere error..** 
1e6a0 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f  Memory corruptio
1e6b0 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f  n, a segmentatio
1e6c0 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65  n fault, or othe
1e6d0 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a  r severe error.*
1e6e0 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  * might result i
1e6f0 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  f sqlite3_free()
1e700 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20   is called with 
1e710 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
1e720 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e  er that.** was n
1e730 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ot obtained from
1e740 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e750 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61  ) or sqlite3_rea
1e760 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lloc()..**.** ^(
1e770 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c  The sqlite3_real
1e780 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  loc() interface 
1e790 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69  attempts to resi
1e7a0 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65  ze a.** prior me
1e7b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1e7c0 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e  to be at least N
1e7d0 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20   bytes, where N 
1e7e0 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64  is the.** second
1e7f0 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65   parameter.  The
1e800 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1e810 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64  on to be resized
1e820 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a   is the first.**
1e830 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20   parameter.)^ ^ 
1e840 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61 72  If the first par
1e850 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1e860 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
1e870 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1e880 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76 69   then its behavi
1e890 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20  or is identical 
1e8a0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71  to calling.** sq
1e8b0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20  lite3_malloc(N) 
1e8c0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
1e8d0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1e8e0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1e8f0 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  oc()..** ^If the
1e900 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1e910 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
1e920 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1e930 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68  r.** negative th
1e940 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
1e950 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20 73  is exactly the s
1e960 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a  ame as calling.*
1e970 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50  * sqlite3_free(P
1e980 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68 65  ) where P is the
1e990 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1e9a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1e9b0 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74  loc()..** ^sqlit
1e9c0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
1e9d0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
1e9e0 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  o a memory alloc
1e9f0 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c  ation.** of at l
1ea00 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1ea10 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20  size or NULL if 
1ea20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72  sufficient memor
1ea30 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  y is unavailable
1ea40 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68  ..** ^If M is th
1ea50 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72  e size of the pr
1ea60 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20  ior allocation, 
1ea70 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79  then min(N,M) by
1ea80 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72  tes.** of the pr
1ea90 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61  ior allocation a
1eaa0 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74  re copied into t
1eab0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
1eac0 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a  buffer returned.
1ead0 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65  ** by sqlite3_re
1eae0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20  alloc() and the 
1eaf0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1eb00 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49   is freed..** ^I
1eb10 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  f sqlite3_reallo
1eb20 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c  c() returns NULL
1eb30 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72  , then the prior
1eb40 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69   allocation.** i
1eb50 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a  s not freed..**.
1eb60 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72  ** ^The memory r
1eb70 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1eb80 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  e3_malloc() and 
1eb90 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1eba0 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  ).** is always a
1ebb0 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61  ligned to at lea
1ebc0 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75  st an 8 byte bou
1ebd0 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a  ndary, or to a.*
1ebe0 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72  * 4 byte boundar
1ebf0 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  y if the [SQLITE
1ec00 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f  _4_BYTE_ALIGNED_
1ec10 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d  MALLOC] compile-
1ec20 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69  time.** option i
1ec30 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e  s used..**.** In
1ec40 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1ec50 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c  3.5.0 and 3.5.1,
1ec60 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65   it was possible
1ec70 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68   to define.** th
1ec80 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45  e SQLITE_OMIT_ME
1ec90 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20  MORY_ALLOCATION 
1eca0 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73  which would caus
1ecb0 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a  e the built-in.*
1ecc0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
1ecd0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
1ece0 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64  es to be omitted
1ecf0 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c 69  .  That capabili
1ed00 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67  ty.** is no long
1ed10 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e  er provided.  On
1ed20 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  ly built-in memo
1ed30 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61  ry allocators ca
1ed40 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n be used..**.**
1ed50 20 50 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65   Prior to SQLite
1ed60 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c   version 3.7.10,
1ed70 20 74 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20   the Windows OS 
1ed80 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 20  interface layer 
1ed90 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79  called.** the sy
1eda0 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
1edb0 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
1edc0 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
1edd0 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
1ede0 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
1edf0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
1ee00 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
1ee10 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
1ee20 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
1ee30 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
1ee40 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
1ee50 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
1ee60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1ee70 20 65 72 72 6f 72 73 20 77 65 72 65 20 64 65 74   errors were det
1ee80 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68  ected, but.** th
1ee90 65 79 20 77 65 72 65 20 72 65 70 6f 72 74 65 64  ey were reported
1eea0 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
1eeb0 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
1eec0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
1eed0 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
1eee0 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
1eef0 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72  * The pointer ar
1ef00 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
1ef10 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
1ef20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1ef30 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  ()].** must be e
1ef40 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
1ef50 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
1ef60 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
1ef70 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  r.** invocation 
1ef80 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1ef90 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
1efa0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
1efb0 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65  t have.** not ye
1efc0 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
1efd0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
1efe0 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
1eff0 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
1f000 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62  y part of.** a b
1f010 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
1f020 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
1f030 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
1f040 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1f050 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1f060 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53  realloc()]..*/.S
1f070 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1f080 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1f090 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
1f0a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1f0b0 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1f0c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1f0d0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
1f0e0 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1f0f0 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1f100 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
1f110 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
1f120 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
1f130 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
1f140 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
1f150 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
1f160 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
1f170 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
1f180 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
1f190 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1f1a0 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
1f1b0 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
1f1c0 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1f1d0 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
1f1e0 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
1f1f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1f200 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
1f210 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1f220 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1f230 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
1f240 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
1f250 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
1f260 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
1f270 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1f280 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
1f290 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1f2a0 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
1f2b0 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
1f2c0 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
1f2d0 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
1f2e0 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
1f2f0 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
1f300 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
1f310 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
1f320 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
1f330 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1f340 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1f350 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
1f360 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
1f370 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
1f380 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1f390 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1f3a0 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
1f3b0 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
1f3c0 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
1f3d0 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
1f3e0 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
1f3f0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
1f400 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
1f410 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1f420 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
1f430 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
1f440 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
1f450 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
1f460 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1f470 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
1f480 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
1f490 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1f4a0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1f4b0 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
1f4c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
1f4d0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
1f4e0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
1f4f0 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
1f500 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
1f510 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
1f520 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
1f530 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1f540 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1f550 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
1f560 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
1f570 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1f580 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
1f590 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
1f5a0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
1f5b0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
1f5c0 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
1f5d0 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
1f5e0 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
1f5f0 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
1f600 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
1f610 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
1f620 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
1f630 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
1f640 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
1f650 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
1f660 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
1f670 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
1f680 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
1f690 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
1f6a0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
1f6b0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
1f6c0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
1f6d0 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
1f6e0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
1f6f0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1f700 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
1f710 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
1f720 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
1f730 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
1f740 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
1f750 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
1f760 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
1f770 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
1f780 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
1f790 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
1f7a0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
1f7b0 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72   invoked (either
1f7c0 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62   internally or b
1f7d0 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  y.** the applica
1f7e0 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69  tion) the PRNG i
1f7f0 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  s seeded using r
1f800 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
1f810 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78  ed.** from the x
1f820 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
1f830 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
1f840 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1f850 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c  bject..** ^On al
1f860 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
1f870 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
1f880 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
1f890 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
1f8a0 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
1f8b0 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
1f8c0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1f8d0 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
1f8e0 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53  .** method..*/.S
1f8f0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1f900 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
1f910 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
1f920 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f930 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
1f940 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
1f950 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1f960 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
1f970 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
1f980 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
1f990 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
1f9a0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1f9b0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
1f9c0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
1f9d0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
1f9e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1f9f0 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1fa00 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
1fa10 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
1fa20 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
1fa30 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1fa40 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
1fa50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fa60 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
1fa70 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1fa80 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1fa90 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
1faa0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
1fab0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
1fac0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
1fad0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
1fae0 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
1faf0 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
1fb00 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
1fb10 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1fb20 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1fb30 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
1fb40 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
1fb50 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
1fb60 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1fb70 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
1fb80 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1fb90 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
1fba0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
1fbb0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
1fbc0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
1fbd0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
1fbe0 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
1fbf0 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
1fc00 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
1fc10 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
1fc20 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
1fc30 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
1fc40 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
1fc50 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
1fc60 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
1fc70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fc80 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1fc90 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1fca0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
1fcb0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
1fcc0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
1fcd0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
1fce0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fcf0 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1fd00 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1fd10 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
1fd20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1fd30 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1fd40 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
1fd50 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
1fd60 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1fd70 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
1fd80 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
1fd90 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
1fda0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
1fdb0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1fdc0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
1fdd0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1fde0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1fdf0 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1fe00 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1fe10 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1fe20 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1fe30 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1fe40 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
1fe50 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
1fe60 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
1fe70 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1fe80 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1fe90 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1fea0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1feb0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
1fec0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
1fed0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1fee0 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
1fef0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1ff00 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
1ff10 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1ff20 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
1ff30 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
1ff40 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1ff50 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
1ff60 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
1ff70 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
1ff80 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1ff90 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
1ffa0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1ffb0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
1ffc0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1ffd0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
1ffe0 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
1fff0 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
20000 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
20010 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
20020 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
20030 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
20040 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
20050 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
20060 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
20070 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
20080 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
20090 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
200a0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
200b0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
200c0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
200d0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
200e0 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
200f0 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
20100 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
20110 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
20120 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
20130 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
20140 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
20150 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
20160 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
20170 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
20180 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
20190 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
201a0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
201b0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
201c0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
201d0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
201e0 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
201f0 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
20200 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
20210 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
20220 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
20230 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
20240 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
20250 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
20260 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
20270 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
20280 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
20290 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
202a0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
202b0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
202c0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
202d0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
202e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
202f0 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
20300 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
20310 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
20320 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
20330 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
20340 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
20350 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
20360 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
20370 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
20380 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
20390 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
203a0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
203b0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
203c0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
203d0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
203e0 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
203f0 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
20400 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
20410 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
20420 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
20430 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
20440 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
20450 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
20460 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
20470 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
20480 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
20490 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
204a0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
204b0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
204c0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
204d0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
204e0 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
204f0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
20500 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
20510 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
20520 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
20530 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
20540 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
20550 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
20560 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
20570 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
20580 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
20590 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
205a0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
205b0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
205c0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
205d0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
205e0 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
205f0 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
20600 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
20610 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
20620 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
20630 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
20640 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
20650 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
20660 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
20670 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
20680 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
20690 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
206a0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
206b0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
206c0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
206d0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
206e0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
206f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
20700 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20710 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
20720 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
20730 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
20740 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20750 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
20760 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20770 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
20780 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
20790 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
207a0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
207b0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
207c0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
207d0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
207e0 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
207f0 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
20800 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
20810 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
20820 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
20830 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
20840 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
20850 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
20860 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
20870 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
20880 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
20890 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
208a0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
208b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
208c0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
208d0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
208e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
208f0 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
20900 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
20910 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20920 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
20930 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
20940 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
20950 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
20960 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
20970 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
20980 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
20990 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
209a0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
209b0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
209c0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
209d0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
209e0 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
209f0 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
20a00 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
20a10 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
20a20 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
20a30 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
20a40 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
20a50 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
20a60 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53  ema change..*/.S
20a70 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
20a80 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20a90 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
20aa0 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
20ab0 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
20ac0 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
20ad0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
20ae0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
20af0 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
20b00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20b10 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
20b20 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
20b30 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
20b40 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
20b50 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20b60 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
20b70 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
20b80 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
20b90 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
20ba0 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
20bb0 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
20bc0 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
20bd0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
20be0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
20bf0 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
20c00 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
20c10 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
20c20 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
20c30 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
20c40 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
20c50 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
20c60 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
20c70 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
20c80 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
20c90 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d  K | return code]
20ca0 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  .** from the [sq
20cb0 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f  lite3_vtab_on_co
20cc0 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66  nflict()] interf
20cd0 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
20ce0 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
20cf0 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
20d00 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
20d10 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
20d20 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
20d30 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
20d40 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
20d50 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
20d60 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
20d70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
20d80 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
20d90 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
20da0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
20db0 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
20dc0 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
20dd0 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
20de0 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
20df0 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
20e00 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
20e10 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
20e20 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
20e30 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
20e40 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
20e50 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
20e60 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
20e70 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
20e80 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
20e90 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
20ea0 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
20eb0 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
20ec0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20ed0 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
20ee0 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
20ef0 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
20f00 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
20f10 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
20f20 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
20f30 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
20f40 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
20f50 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
20f60 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
20f70 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20f80 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
20f90 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
20fa0 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
20fb0 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
20fc0 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
20fd0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
20fe0 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
20ff0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
21000 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
21010 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
21020 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
21030 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
21040 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
21050 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
21060 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
21070 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
21080 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
21090 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
210a0 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
210b0 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
210c0 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
210d0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
210e0 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
210f0 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
21100 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
21110 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
21120 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
21130 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
21140 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21150 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21160 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
21170 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
21180 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21190 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
211a0 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
211b0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
211c0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
211d0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
211e0 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
211f0 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
21200 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21210 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21220 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21230 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
21240 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
21250 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
21260 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
21270 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21280 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
21290 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
212a0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
212b0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
212c0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
212d0 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
212e0 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
212f0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
21300 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21310 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
21320 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
21330 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
21340 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
21350 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21360 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
21370 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
21380 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
21390 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
213a0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
213b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
213c0 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
213d0 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
213e0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
213f0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21400 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
21410 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21420 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
21430 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
21440 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21450 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
21460 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
21470 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
21480 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
21490 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
214a0 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
214b0 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
214c0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
214d0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
214e0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
214f0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
21500 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
21510 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
21520 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
21530 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21540 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
21550 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
21560 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21570 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21580 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21590 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
215a0 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
215b0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
215c0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
215d0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
215e0 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
215f0 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
21600 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
21610 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21620 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21630 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
21640 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
21650 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
21660 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21670 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21680 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
21690 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
216a0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
216b0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
216c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
216d0 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
216e0 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
216f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21700 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21710 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21720 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
21730 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
21740 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
21750 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
21760 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
21770 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
21780 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
21790 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
217a0 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
217b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
217c0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
217d0 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
217e0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
217f0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21800 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
21810 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
21820 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
21830 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
21840 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21850 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
21860 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
21870 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
21880 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
21890 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
218a0 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
218b0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
218c0 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
218d0 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
218e0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
218f0 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
21900 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
21910 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
21920 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
21930 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
21940 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
21950 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
21960 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
21970 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
21980 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21990 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
219a0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
219b0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
219c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
219d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
219e0 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
219f0 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
21a00 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21a10 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21a20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21a30 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
21a40 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
21a50 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21a60 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
21a70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21a80 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
21a90 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
21aa0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21ab0 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
21ac0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21ad0 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
21ae0 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
21af0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21b00 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
21b10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21b20 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
21b30 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
21b40 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
21b50 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
21b60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21b70 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
21b80 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
21b90 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
21ba0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21bb0 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
21bc0 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
21bd0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
21be0 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
21bf0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
21c00 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
21c10 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
21c20 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
21c30 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
21c40 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
21c50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
21c60 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
21c70 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
21c80 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
21c90 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
21ca0 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
21cb0 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
21cc0 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
21cd0 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
21ce0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
21cf0 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
21d00 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
21d10 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
21d20 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
21d30 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
21d40 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
21d50 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
21d60 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
21d70 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
21d80 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
21d90 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
21da0 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
21db0 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
21dc0 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
21dd0 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
21de0 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
21df0 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
21e00 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
21e10 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
21e20 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  igger.)^.**.** ^
21e30 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
21e40 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
21e50 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
21e60 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
21e70 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
21e80 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
21e90 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
21ea0 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
21eb0 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
21ec0 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
21ed0 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
21ee0 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
21ef0 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
21f00 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
21f10 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
21f20 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
21f30 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
21f40 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
21f50 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
21f60 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
21f70 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
21f80 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
21f90 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
21fa0 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
21fb0 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
21fc0 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
21fd0 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
21fe0 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
21ff0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
22000 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
22010 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
22020 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
22030 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
22040 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
22050 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
22060 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
22070 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
22080 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
22090 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
220a0 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
220b0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
220c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
220d0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
220e0 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
220f0 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
22100 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
22110 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  oid*);.SQLITE_AP
22120 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  I SQLITE_EXPERIM
22130 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
22140 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
22150 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
22160 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
22170 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
22180 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
22190 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
221a0 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
221b0 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
221c0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
221d0 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
221e0 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
221f0 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
22200 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
22210 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
22220 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
22230 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
22240 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
22250 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
22260 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
22270 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
22280 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
22290 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
222a0 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
222b0 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
222c0 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
222d0 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
222e0 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
222f0 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
22300 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
22310 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
22320 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
22330 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
22340 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
22350 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
22360 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
22370 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72   N is the number
22380 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
22390 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
223a0 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
223b0 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
223c0 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
223d0 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
223e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a  he callback X..*
223f0 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
22400 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
22410 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
22420 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
22430 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
22440 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
22450 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
22460 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
22470 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
22480 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
22490 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
224a0 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
224b0 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
224c0 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
224d0 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
224e0 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
224f0 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
22500 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
22510 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
22520 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
22530 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
22540 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
22550 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
22560 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
22570 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
22580 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
22590 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
225a0 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
225b0 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
225c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
225d0 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
225e0 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
225f0 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
22600 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
22610 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
22620 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
22630 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
22640 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
22650 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
22660 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
22670 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22680 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
22690 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
226a0 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
226b0 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
226c0 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
226d0 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
226e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
226f0 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
22700 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
22710 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
22720 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
22730 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22740 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
22750 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
22760 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
22770 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
22780 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
22790 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
227a0 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
227b0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
227c0 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
227d0 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
227e0 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
227f0 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
22800 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
22810 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
22820 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
22830 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
22840 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
22850 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
22860 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
22870 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
22880 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
22890 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
228a0 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
228b0 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
228c0 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
228d0 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
228e0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
228f0 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
22900 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
22910 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
22920 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
22930 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
22940 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
22950 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
22960 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
22970 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
22980 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
22990 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
229a0 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
229b0 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
229c0 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
229d0 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
229e0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
229f0 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
22a00 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
22a10 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
22a20 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
22a30 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
22a40 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
22a50 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
22a60 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
22a70 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
22a80 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
22a90 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
22aa0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
22ab0 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
22ac0 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
22ad0 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
22ae0 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
22af0 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
22b00 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
22b10 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
22b20 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
22b30 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
22b40 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
22b50 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
22b60 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
22b70 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
22b80 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
22b90 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
22ba0 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
22bb0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
22bc0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
22bd0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
22be0 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
22bf0 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
22c00 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
22c10 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
22c20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
22c30 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
22c40 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
22c50 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
22c60 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
22c70 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
22c80 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
22c90 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
22ca0 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
22cb0 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
22cc0 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
22cd0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
22ce0 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
22cf0 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
22d00 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
22d10 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
22d20 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
22d30 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
22d40 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
22d50 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
22d60 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
22d70 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
22d80 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
22d90 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
22da0 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
22db0 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
22dc0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
22dd0 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
22de0 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
22df0 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
22e00 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
22e10 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
22e20 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22e30 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
22e40 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
22e50 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
22e60 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
22e70 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
22e80 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
22e90 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
22ea0 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
22eb0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
22ec0 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
22ed0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
22ee0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
22ef0 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
22f00 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
22f10 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
22f20 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
22f30 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
22f40 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
22f50 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
22f60 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
22f70 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
22f80 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
22f90 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
22fa0 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
22fb0 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
22fc0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
22fd0 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
22fe0 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
22ff0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
23000 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
23010 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
23020 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
23030 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
23040 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
23050 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
23060 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
23070 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
23080 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
23090 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
230a0 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
230b0 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
230c0 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
230d0 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
230e0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
230f0 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
23100 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
23110 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
23120 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
23130 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
23140 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
23150 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
23160 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
23170 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
23180 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
23190 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
231a0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
231b0 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
231c0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
231d0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
231e0 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
231f0 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
23200 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
23210 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
23220 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
23230 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
23240 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
23250 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
23260 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
23270 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
23280 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
23290 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
232a0 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
232b0 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
232c0 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
232d0 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
232e0 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
232f0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
23300 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
23310 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
23320 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
23330 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
23340 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
23350 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
23360 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
23370 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
23380 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
23390 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
233a0 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
233b0 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
233c0 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
233d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
233e0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
233f0 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
23400 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
23410 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
23420 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
23430 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
23440 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
23450 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
23460 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
23470 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
23480 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
23490 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
234a0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
234b0 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
234c0 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
234d0 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
234e0 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
234f0 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
23500 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
23510 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
23520 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
23530 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
23540 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
23550 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
23560 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
23570 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
23580 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
23590 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
235a0 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
235b0 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
235c0 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
235d0 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
235e0 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
235f0 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
23600 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
23610 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
23620 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
23630 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
23640 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
23650 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
23660 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
23670 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
23680 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
23690 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
236a0 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
236b0 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
236c0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
236d0 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
236e0 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
236f0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
23700 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
23710 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
23720 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
23730 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
23740 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
23750 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
23760 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
23770 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
23780 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
23790 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
237a0 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
237b0 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
237c0 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
237d0 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
237e0 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
237f0 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
23800 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
23810 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
23820 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
23830 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
23840 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
23850 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
23860 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
23870 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
23880 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
23890 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
238a0 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
238b0 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
238c0 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
238d0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
238e0 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
238f0 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
23900 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
23910 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
23920 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
23930 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
23940 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
23950 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
23960 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
23970 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
23980 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
23990 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
239a0 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
239b0 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
239c0 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
239d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
239e0 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
239f0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
23a00 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
23a10 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
23a20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
23a30 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
23a40 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
23a50 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
23a60 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
23a70 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
23a80 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
23a90 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
23aa0 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
23ab0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
23ac0 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
23ad0 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
23ae0 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
23af0 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
23b00 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
23b10 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
23b20 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
23b30 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
23b40 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
23b50 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
23b60 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
23b70 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
23b80 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
23b90 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
23ba0 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
23bb0 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
23bc0 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
23bd0 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
23be0 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
23bf0 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
23c00 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
23c10 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
23c20 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
23c30 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
23c40 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
23c50 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
23c60 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
23c70 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
23c80 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
23c90 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
23ca0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
23cb0 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
23cc0 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
23cd0 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
23ce0 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
23cf0 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
23d00 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
23d10 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
23d20 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
23d30 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
23d40 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
23d50 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
23d60 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
23d70 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
23d80 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
23d90 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
23da0 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
23db0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
23dc0 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
23dd0 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  ** ^On windows, 
23de0 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
23df0 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
23e00 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
23e10 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
23e20 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
23e30 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ..**.** [[core U
23e40 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
23e50 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
23e60 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
23e70 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
23e80 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
23e90 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
23ea0 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
23eb0 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
23ec0 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
23ed0 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
23ee0 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
23ef0 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
23f00 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
23f10 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
23f20 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
23f30 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
23f40 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
23f50 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
23f60 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
23f70 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
23f80 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
23f90 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
23fa0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
23fb0 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
23fc0 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
23fd0 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
23fe0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
23ff0 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
24000 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
24010 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
24020 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
24030 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
24040 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
24050 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
24060 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
24070 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
24080 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
24090 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
240a0 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
240b0 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
240c0 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
240d0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
240e0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
240f0 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
24100 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
24110 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
24120 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
24130 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24140 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
24150 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
24160 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
24170 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
24180 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
24190 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22 2c  ",.**     "rwc",
241a0 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41 74   or "memory". At
241b0 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20  tempting to set 
241c0 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20  it to any other 
241d0 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20 20  value is.**     
241e0 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20  an error)^. .** 
241f0 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20      ^If "ro" is 
24200 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20  specified, then 
24210 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
24220 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d  opened for read-
24230 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63  only .**     acc
24240 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20  ess, just as if 
24250 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
24260 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20  _READONLY] flag 
24270 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20  had been set in 
24280 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72  the .**     thir
24290 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
242a0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
242b0 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
242c0 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
242d0 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
242e0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
242f0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
24300 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
24310 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
24320 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
24330 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
24340 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
24350 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
24360 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
24370 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
24380 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
24390 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
243a0 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
243b0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
243c0 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
243d0 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
243e0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
243f0 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
24400 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
24410 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
24420 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
24430 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
24440 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
24450 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
24460 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
24470 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
24480 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
24490 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
244a0 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
244b0 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
244c0 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
244d0 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
244e0 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
244f0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
24500 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
24510 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
24520 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
24530 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
24540 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
24550 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
24560 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
24570 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
24580 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
24590 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
245a0 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
245b0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
245c0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
245d0 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
245e0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
245f0 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
24600 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
24610 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
24620 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
24630 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
24640 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
24650 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
24660 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
24670 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
24680 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
24690 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
246a0 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
246b0 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
246c0 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
246d0 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
246e0 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
246f0 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72   any behaviour r
24700 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
24710 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
24720 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
24730 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
24740 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
24750 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  lag..** </ul>.**
24760 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
24770 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
24780 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
24790 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
247a0 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
247b0 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
247c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
247d0 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
247e0 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
247f0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
24800 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
24810 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
24820 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
24830 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
24840 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
24850 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
24860 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
24870 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
24880 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
24890 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
248a0 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
248b0 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
248c0 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
248d0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
248e0 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
248f0 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
24900 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
24910 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
24920 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
24930 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
24940 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
24950 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
24960 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
24970 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
24980 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
24990 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
249a0 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
249b0 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
249c0 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
249d0 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
249e0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
249f0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
24a00 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
24a10 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
24a20 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
24a30 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
24a40 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
24a50 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
24a60 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
24a70 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
24a80 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
24a90 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
24aa0 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
24ab0 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
24ac0 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
24ad0 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
24ae0 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
24af0 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
24b00 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
24b10 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
24b20 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
24b30 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
24b40 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
24b50 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
24b60 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
24b70 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
24b80 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
24b90 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
24ba0 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
24bb0 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
24bc0 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
24bd0 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
24be0 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
24bf0 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
24c00 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
24c10 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
24c20 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
24c30 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
24c40 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
24c50 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
24c60 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
24c70 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
24c80 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
24c90 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
24ca0 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
24cb0 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
24cc0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
24cd0 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
24ce0 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
24cf0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
24d00 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
24d10 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c  fs=unix-nolock <
24d20 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
24d30 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
24d40 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
24d50 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
24d60 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  VFS "unix-nolock
24d70 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
24d80 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
24d90 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
24da0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
24db0 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
24dc0 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
24dd0 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
24de0 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
24df0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
24e00 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
24e10 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
24e20 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
24e30 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
24e40 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
24e50 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
24e60 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
24e70 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
24e80 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
24e90 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
24ea0 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
24eb0 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
24ec0 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
24ed0 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
24ee0 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
24ef0 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
24f00 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
24f10 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
24f20 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
24f30 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
24f40 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
24f50 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
24f60 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
24f70 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
24f80 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
24f90 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
24fa0 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
24fb0 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
24fc0 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
24fd0 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
24fe0 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
24ff0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
25000 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
25010 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
25020 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
25030 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
25040 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
25050 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
25060 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
25070 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
25080 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
25090 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
250a0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
250b0 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
250c0 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
250d0 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
250e0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
250f0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
25100 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
25110 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
25120 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
25130 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
25140 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
25150 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
25160 6e 5f 76 32 28 29 2e 0a 2a 2f 0a 53 51 4c 49 54  n_v2()..*/.SQLIT
25170 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
25180 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
25190 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
251a0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
251b0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
251c0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
251d0 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
251e0 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
251f0 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54  ndle */.);.SQLIT
25200 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
25210 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
25220 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
25230 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
25240 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
25250 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
25260 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
25270 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
25280 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51   handle */.);.SQ
25290 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
252a0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a 20 20  ite3_open_v2(.  
252b0 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65  const char *file
252c0 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62  name,   /* Datab
252d0 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54  ase filename (UT
252e0 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65  F-8) */.  sqlite
252f0 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20 20 20  3 **ppDb,       
25300 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65    /* OUT: SQLite
25310 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20   db handle */.  
25320 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20 20 20  int flags,      
25330 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61 67 73          /* Flags
25340 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
25350 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20 2f 2a   *zVfs        /*
25360 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d 6f 64   Name of VFS mod
25370 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a 29 3b  ule to use */.);
25380 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
25390 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65 73 20  : Obtain Values 
253a0 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65 74 65  For URI Paramete
253b0 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  rs.**.** These a
253c0 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75 74 69  re utility routi
253d0 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f 20 56  nes, useful to V
253e0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
253f0 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b 0a 2a  ns, that check.*
25400 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20 64 61  * to see if a da
25410 74 61 62 61 73 65 20 66 69 6c 65 20 77 61 73 20  tabase file was 
25420 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e 74 61  a URI that conta
25430 69 6e 65 64 20 61 20 73 70 65 63 69 66 69 63 20  ined a specific 
25440 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61 6d 65  query .** parame
25450 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f 20 6f  ter, and if so o
25460 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c 75 65  btains the value
25470 20 6f 66 20 74 68 61 74 20 71 75 65 72 79 20 70   of that query p
25480 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
25490 49 66 20 46 20 69 73 20 74 68 65 20 64 61 74 61  If F is the data
254a0 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 70 6f  base filename po
254b0 69 6e 74 65 72 20 70 61 73 73 65 64 20 69 6e 74  inter passed int
254c0 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20 6d 65  o the xOpen() me
254d0 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20 56 46  thod of .** a VF
254e0 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
254f0 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67 73 20   when the flags 
25500 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
25510 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f 72 20  en() has one or 
25520 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68 65 20  .** more of the 
25530 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
25540 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ] or [SQLITE_OPE
25550 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74 73 20  N_MAIN_DB] bits 
25560 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69 73 20  set and.** P is 
25570 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
25580 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2c  query parameter,
25590 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
255a0 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
255b0 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68 65 20  ,P) returns the 
255c0 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50 0a 2a  value of the P.*
255d0 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66 20 69  * parameter if i
255e0 74 20 65 78 69 73 74 73 20 6f 72 20 61 20 4e 55  t exists or a NU
255f0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 50 20  LL pointer if P 
25600 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
25610 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79 20 70  as a .** query p
25620 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e 20 20  arameter on F.  
25630 49 66 20 50 20 69 73 20 61 20 71 75 65 72 79 20  If P is a query 
25640 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46 0a 2a  parameter of F.*
25650 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69 63 69  * has no explici
25660 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 73 71  t value, then sq
25670 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
25680 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
25690 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  .** a pointer to
256a0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
256b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
256c0 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
256d0 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 61  F,P,B) routine a
256e0 73 73 75 6d 65 73 20 74 68 61 74 20 50 20 69 73  ssumes that P is
256f0 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61   a boolean.** pa
25700 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75  rameter and retu
25710 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f 72 20  rns true (1) or 
25720 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f 72 64  false (0) accord
25730 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c 75 65  ing to the value
25740 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65 20 73  .** of P.  The s
25750 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65  qlite3_uri_boole
25760 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e  an(F,P,B) routin
25770 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28  e returns true (
25780 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76 61 6c  1) if the.** val
25790 75 65 20 6f 66 20 71 75 65 72 79 20 70 61 72 61  ue of query para
257a0 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f  meter P is one o
257b0 66 20 22 79 65 73 22 2c 20 22 74 72 75 65 22 2c  f "yes", "true",
257c0 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e 79 0a   or "on" in any.
257d0 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20 74 68  ** case or if th
257e0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
257f0 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e  ith a non-zero n
25800 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a 2a 20  umber.  The .** 
25810 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
25820 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
25830 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61 6c 73  nes returns fals
25840 65 20 28 30 29 20 69 66 20 74 68 65 20 76 61 6c  e (0) if the val
25850 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79 20 70  ue of.** query p
25860 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e  arameter P is on
25870 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61 6c 73  e of "no", "fals
25880 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69 6e 20  e", or "off" in 
25890 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a 20 69  any case or.** i
258a0 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
258b0 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65 72 69  ns with a numeri
258c0 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20 69 73  c zero.  If P is
258d0 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a 2a 20   not a query.** 
258e0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 20 6f  parameter on F o
258f0 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  r if the value o
25900 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f 74 20  f P is does not 
25910 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74 68 65  match any of the
25920 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65 6e 20  .** above, then 
25930 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
25940 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
25950 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a  ns (B!=0)..**.**
25960 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69   The sqlite3_uri
25970 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20 72 6f  _int64(F,P,D) ro
25980 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73 20 74  utine converts t
25990 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 6e  he value of P in
259a0 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74 20 73  to a.** 64-bit s
259b0 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20 61 6e  igned integer an
259c0 64 20 72 65 74 75 72 6e 73 20 74 68 61 74 20 69  d returns that i
259d0 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69 66 20  nteger, or D if 
259e0 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 65 78  P does not.** ex
259f0 69 73 74 2e 20 20 49 66 20 74 68 65 20 76 61 6c  ist.  If the val
25a00 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d 65 74  ue of P is somet
25a10 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
25a20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 6e  an integer, then
25a30 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65 74 75  .** zero is retu
25a40 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20  rned..** .** If 
25a50 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  F is a NULL poin
25a60 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ter, then sqlite
25a70 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
25a80 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  F,P) returns NUL
25a90 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  L and.** sqlite3
25aa0 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
25ab0 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e 20 20  ,B) returns B.  
25ac0 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20 4e 55  If F is not a NU
25ad0 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64 0a 2a  LL pointer and.*
25ae0 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62  * is not a datab
25af0 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  ase file pathnam
25b00 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 53  e pointer that S
25b10 51 4c 69 74 65 20 70 61 73 73 65 64 20 69 6e 74  QLite passed int
25b20 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a 20 56  o the xOpen.** V
25b30 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20  FS method, then 
25b40 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
25b50 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
25b60 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72  undefined and pr
25b70 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65 73 69  obably.** undesi
25b80 72 61 62 6c 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  rable..*/.SQLITE
25b90 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20  _API const char 
25ba0 2a 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72  *sqlite3_uri_par
25bb0 61 6d 65 74 65 72 28 63 6f 6e 73 74 20 63 68 61  ameter(const cha
25bc0 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 2c 20 63 6f  r *zFilename, co
25bd0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
25be0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
25bf0 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  t sqlite3_uri_bo
25c00 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72  olean(const char
25c10 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63   *zFile, const c
25c20 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74  har *zParam, int
25c30 20 62 44 65 66 61 75 6c 74 29 3b 0a 53 51 4c 49   bDefault);.SQLI
25c40 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69  TE_API sqlite3_i
25c50 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72 69  nt64 sqlite3_uri
25c60 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68 61  _int64(const cha
25c70 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  r*, const char*,
25c80 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
25c90 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
25ca0 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20 41  F: Error Codes A
25cb0 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a 2a  nd Messages.**.*
25cc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
25cd0 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66 61  rrcode() interfa
25ce0 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
25cf0 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20 63  umeric [result c
25d00 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
25d10 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
25d20 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20 72  ] for the most r
25d30 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71 6c  ecent failed sql
25d40 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c 0a  ite3_* API call.
25d50 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ** associated wi
25d60 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
25d70 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20 61  onnection]. If a
25d80 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c 20   prior API call 
25d90 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74 68  failed.** but th
25da0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41 50  e most recent AP
25db0 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65 64  I call succeeded
25dc0 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
25dd0 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74  ue from.** sqlit
25de0 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73 20  e3_errcode() is 
25df0 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  undefined.  ^The
25e00 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
25e10 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20 69  d_errcode().** i
25e20 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65 20  nterface is the 
25e30 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61 74  same except that
25e40 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72   it always retur
25e50 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74 65  ns the .** [exte
25e60 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
25e70 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74 65  ] even when exte
25e80 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
25e90 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c 65  s are.** disable
25ea0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
25eb0 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20 61  lite3_errmsg() a
25ec0 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  nd sqlite3_errms
25ed0 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e 67  g16() return Eng
25ee0 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a  lish-language.**
25ef0 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63 72   text that descr
25f00 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c 20  ibes the error, 
25f10 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38 20  as either UTF-8 
25f20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65 63  or UTF-16 respec
25f30 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d  tively..** ^(Mem
25f40 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20  ory to hold the 
25f50 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74  error message st
25f60 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20  ring is managed 
25f70 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54  internally..** T
25f80 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
25f90 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
25fa0 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65 65  worry about free
25fb0 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e 0a  ing the result..
25fc0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20  ** However, the 
25fd0 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69 67  error string mig
25fe0 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74 65  ht be overwritte
25ff0 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65 64  n or deallocated
26000 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e   by.** subsequen
26010 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65 72  t calls to other
26020 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
26030 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a  e functions.)^.*
26040 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65  *.** When the se
26050 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
26060 69 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20  ing mode] is in 
26070 75 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65  use, it might be
26080 20 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61   the.** case tha
26090 74 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72  t a second error
260a0 20 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70   occurs on a sep
260b0 61 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20  arate thread in 
260c0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74  between.** the t
260d0 69 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74  ime of the first
260e0 20 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63   error and the c
260f0 61 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74  all to these int
26100 65 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e  erfaces..** When
26110 20 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74   that happens, t
26120 68 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20  he second error 
26130 77 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64  will be reported
26140 20 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20   since these.** 
26150 69 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79  interfaces alway
26160 73 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73  s report the mos
26170 74 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e  t recent result.
26180 20 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68    To avoid.** th
26190 69 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20  is, each thread 
261a0 63 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75  can obtain exclu
261b0 73 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20  sive use of the 
261c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
261d0 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e  tion] D.** by in
261e0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
261f0 6d 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71  mutex_enter]([sq
26200 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
26210 44 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e  D)) before begin
26220 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44  ning.** to use D
26230 20 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73   and invoking [s
26240 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61  qlite3_mutex_lea
26250 76 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f  ve]([sqlite3_db_
26260 6d 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72  mutex](D)) after
26270 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f  .** all calls to
26280 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20   the interfaces 
26290 6c 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20  listed here are 
262a0 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a  completed..**.**
262b0 20 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65   If an interface
262c0 20 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49   fails with SQLI
262d0 54 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20  TE_MISUSE, that 
262e0 6d 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66  means the interf
262f0 61 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b  ace.** was invok
26300 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62  ed incorrectly b
26310 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
26320 6e 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65  n.  In that case
26330 2c 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63  , the.** error c
26340 6f 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20  ode and message 
26350 6d 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62  may or may not b
26360 65 20 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45  e set..*/.SQLITE
26370 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
26380 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
26390 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
263a0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
263b0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73  tended_errcode(s
263c0 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c  qlite3 *db);.SQL
263d0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
263e0 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d  ar *sqlite3_errm
263f0 73 67 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51  sg(sqlite3*);.SQ
26400 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
26410 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
26420 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
26430 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
26440 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
26450 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
26460 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
26470 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
26480 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
26490 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
264a0 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
264b0 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
264c0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
264d0 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
264e0 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
264f0 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
26500 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
26510 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
26520 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
26530 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
26540 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
26550 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
26560 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
26570 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
26580 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
26590 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
265a0 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
265b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
265c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
265d0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
265e0 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
265f0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
26600 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
26610 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
26620 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
26630 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
26640 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
26650 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
26660 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
26670 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
26680 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
26690 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
266a0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
266b0 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
266c0 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
266d0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
266e0 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
266f0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
26700 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
26710 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
26720 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
26730 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
26740 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
26750 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
26760 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
26770 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
26780 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
26790 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
267a0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
267b0 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
267c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
267d0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
267e0 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
267f0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
26800 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
26810 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
26820 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
26830 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
26840 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
26850 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
26860 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
26870 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
26880 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
26890 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
268a0 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
268b0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
268c0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
268d0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
268e0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
268f0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
26900 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
26910 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
26920 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
26930 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
26940 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
26950 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
26960 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
26970 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
26980 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
26990 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
269a0 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
269b0 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
269c0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
269d0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
269e0 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
269f0 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
26a00 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
26a10 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
26a20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
26a30 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
26a40 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
26a50 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
26a60 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
26a70 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
26a80 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
26a90 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
26aa0 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
26ab0 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
26ac0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
26ad0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
26ae0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
26af0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
26b00 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
26b10 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
26b20 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
26b30 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
26b40 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
26b50 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
26b60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
26b70 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
26b80 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
26b90 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
26ba0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
26bb0 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
26bc0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
26bd0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
26be0 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
26bf0 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
26c00 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
26c10 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
26c20 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
26c30 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
26c40 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
26c50 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
26c60 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
26c70 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
26c80 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
26c90 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
26ca0 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
26cb0 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
26cc0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
26cd0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
26ce0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
26cf0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
26d00 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
26d10 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
26d20 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
26d30 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
26d40 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
26d50 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
26d60 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
26d70 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
26d80 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
26d90 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
26da0 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
26db0 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
26dc0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
26dd0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
26de0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
26df0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
26e00 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
26e10 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
26e20 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
26e30 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
26e40 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
26e50 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
26e60 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
26e70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
26e80 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
26e90 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
26ea0 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
26eb0 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
26ec0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
26ed0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
26ee0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
26ef0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
26f00 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
26f10 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
26f20 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
26f30 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
26f40 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
26f50 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
26f60 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
26f70 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  leases..*/.SQLIT
26f80 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
26f90 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
26fa0 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
26fb0 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
26fc0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
26fd0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
26fe0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
26ff0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
27000 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
27010 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
27020 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
27030 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
27040 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
27050 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
27060 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
27070 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
27080 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
27090 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
270a0 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
270b0 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
270c0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
270d0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
270e0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
270f0 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
27100 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
27110 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
27120 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27130 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
27140 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
27150 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
27160 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
27170 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
27180 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
27190 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
271a0 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
271b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
271c0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
271d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
271e0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
271f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
27200 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
27210 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
27220 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
27230 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
27240 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
27250 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
27260 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
27270 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
27280 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
27290 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
272a0 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
272b0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
272c0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
272d0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
272e0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
272f0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
27300 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
27310 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
27320 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
27330 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
27340 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
27350 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
27360 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
27370 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
27380 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
27390 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
273a0 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
273b0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
273c0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
273d0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
273e0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
273f0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
27400 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
27410 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
27420 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
27430 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
27440 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
27450 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
27460 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
27470 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
27480 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
27490 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
274a0 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
274b0 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
274c0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
274d0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
274e0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
274f0 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
27500 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
27510 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
27520 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
27530 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
27540 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
27550 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
27560 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
27570 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
27580 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
27590 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
275a0 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
275b0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
275c0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
275d0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
275e0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
275f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27600 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
27610 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
27620 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
27630 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
27640 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
27650 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
27660 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
27670 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27680 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
27690 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
276a0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
276b0 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
276c0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
276d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
276e0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
276f0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
27700 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
27710 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
27720 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
27730 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
27740 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
27750 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
27760 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
27770 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
27780 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
27790 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
277a0 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
277b0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
277c0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
277d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
277e0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
277f0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
27800 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
27810 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
27820 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
27830 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
27840 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  ers.</dd>)^.** <
27850 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
27860 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
27870 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
27880 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
27890 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
278a0 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
278b0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
278c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
278d0 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
278e0 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
278f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
27900 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
27910 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
27920 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27930 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
27940 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
27950 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27960 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
27970 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
27980 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27990 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
279a0 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
279b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
279c0 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
279d0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
279e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
279f0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
27a00 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
27a10 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27a20 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
27a30 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
27a40 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
27a50 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
27a60 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
27a70 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
27a80 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
27a90 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
27aa0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
27ab0 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
27ac0 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
27ad0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
27ae0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
27af0 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
27b00 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
27b10 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
27b20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
27b30 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
27b40 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
27b50 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
27b60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
27b70 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
27b80 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
27b90 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
27ba0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
27bb0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
27bc0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
27bd0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
27be0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
27bf0 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
27c00 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
27c10 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
27c20 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
27c30 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
27c40 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
27c50 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
27c60 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
27c70 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
27c80 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27c90 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
27ca0 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
27cb0 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
27cc0 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
27cd0 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
27ce0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
27cf0 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
27d00 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
27d10 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
27d20 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
27d30 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
27d40 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
27d50 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
27d60 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
27d70 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
27d80 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
27d90 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
27da0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
27db0 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
27dc0 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20  l.  ^When nByte 
27dd0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
27de0 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
27df0 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
27e00 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
27e10 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
27e20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
27e30 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
27e40 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
27e50 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
27e60 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
27e70 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
27e80 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
27e90 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
27ea0 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
27eb0 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
27ec0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
27ed0 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
27ee0 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
27ef0 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
27f00 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
27f10 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
27f20 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
27f30 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
27f40 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
27f50 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20  erminator bytes 
27f60 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51  as this saves SQ
27f70 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67  Lite from having
27f80 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f   to.** make a co
27f90 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20  py of the input 
27fa0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
27fb0 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
27fc0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
27fd0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
27fe0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
27ff0 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
28000 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
28010 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
28020 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
28030 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
28040 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
28050 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
28060 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
28070 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
28080 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
28090 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
280a0 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
280b0 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
280c0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
280d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
280e0 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
280f0 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
28100 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
28110 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
28120 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
28130 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
28140 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
28150 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
28160 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
28170 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
28180 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
28190 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
281a0 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
281b0 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
281c0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
281d0 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
281e0 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
281f0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
28200 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
28210 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
28220 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
28230 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
28240 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
28250 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
28260 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
28270 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
28280 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
28290 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
282a0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
282b0 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
282c0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
282d0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
282e0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
282f0 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
28300 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28310 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
28320 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
28330 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
28340 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
28350 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
28360 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
28370 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
28380 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
28390 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
283a0 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
283b0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
283c0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
283d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
283e0 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
283f0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
28400 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
28410 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
28420 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
28430 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
28440 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
28450 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
28460 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
28470 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
28480 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
28490 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
284a0 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
284b0 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
284c0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
284d0 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
284e0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
284f0 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
28500 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
28510 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
28520 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
28530 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
28540 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
28550 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
28560 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ain..** </li>.**
28570 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
28580 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
28590 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
285a0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
285b0 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
285c0 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
285d0 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
285e0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
285f0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
28600 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
28610 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
28620 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
28630 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
28640 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
28650 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
28660 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
28670 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
28680 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
28690 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
286a0 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
286b0 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
286c0 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
286d0 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
286e0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
286f0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
28700 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
28710 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
28720 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
28730 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
28740 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
28750 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
28760 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
28770 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
28780 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
28790 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
287a0 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
287b0 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
287c0 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
287d0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
287e0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
287f0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
28800 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
28810 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
28820 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
28830 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
28840 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
28850 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
28860 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
28870 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
28880 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
28890 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
288a0 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
288b0 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
288c0 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
288d0 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
288e0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
288f0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
28900 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
28910 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
28920 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
28930 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
28940 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
28950 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
28960 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
28970 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
28980 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
28990 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
289a0 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
289b0 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
289c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
289d0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
289e0 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69  .** the .** </li
289f0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51  >.** </ol>.*/.SQ
28a00 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28a10 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
28a20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
28a30 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
28a40 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
28a50 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
28a60 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
28a70 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
28a80 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
28a90 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
28aa0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
28ab0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
28ac0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
28ad0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
28ae0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
28af0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
28b00 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
28b10 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
28b20 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
28b30 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
28b40 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
28b50 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
28b60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
28b70 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28b80 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28b90 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
28ba0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
28bb0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
28bc0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
28bd0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
28be0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
28bf0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
28c00 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
28c10 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
28c20 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
28c30 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
28c40 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
28c50 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
28c60 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
28c70 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
28c80 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
28c90 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
28ca0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
28cb0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
28cc0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28cd0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28ce0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
28cf0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
28d00 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
28d10 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
28d20 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
28d30 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
28d40 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
28d50 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
28d60 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
28d70 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
28d80 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
28d90 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
28da0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
28db0 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
28dc0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
28dd0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
28de0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
28df0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
28e00 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
28e10 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
28e20 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
28e30 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
28e40 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
28e50 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
28e60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
28e70 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
28e80 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
28e90 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
28ea0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
28eb0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
28ec0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
28ed0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
28ee0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
28ef0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28f00 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
28f10 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
28f20 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
28f30 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
28f40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
28f50 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
28f60 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
28f70 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
28f80 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
28f90 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
28fa0 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
28fb0 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
28fc0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
28fd0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
28fe0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
28ff0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
29000 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
29010 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
29020 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
29030 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
29040 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53  re16_v2()]..*/.S
29050 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
29060 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
29070 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
29080 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
29090 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
290a0 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
290b0 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
290c0 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a  e Database.**.**
290d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
290e0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
290f0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
29100 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
29110 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
29120 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
29130 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
29140 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
29150 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
29160 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
29170 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
29180 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
29190 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
291a0 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
291b0 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
291c0 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
291d0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
291e0 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
291f0 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
29200 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
29210 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
29220 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
29230 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
29240 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
29250 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
29260 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
29270 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
29280 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
29290 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
292a0 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
292b0 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
292c0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
292d0 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
292e0 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
292f0 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
29300 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
29310 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
29320 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
29330 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
29340 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
29350 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
29360 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
29370 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
29380 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
29390 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
293a0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
293b0 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
293c0 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
293d0 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
293e0 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
293f0 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
29400 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
29410 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
29420 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
29430 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
29440 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
29450 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
29460 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
29470 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
29480 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
29490 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
294a0 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
294b0 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
294c0 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
294d0 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
294e0 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
294f0 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
29500 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
29510 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
29520 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
29530 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
29540 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
29550 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
29560 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
29570 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
29580 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
29590 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
295a0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
295b0 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
295c0 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
295d0 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  disk..*/.SQLITE_
295e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
295f0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
29600 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
29610 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
29620 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
29630 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
29640 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
29650 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Reset.**.** ^The
29660 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
29670 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
29680 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
29690 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
296a0 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
296b0 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
296c0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
296d0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
296e0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
296f0 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
29700 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
29710 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
29720 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
29730 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
29740 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
29750 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
29760 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
29770 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
29780 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
29790 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
297a0 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
297b0 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
297c0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
297d0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
297e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
297f0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
29800 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
29810 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
29820 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
29830 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
29840 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
29850 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
29860 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
29870 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
29880 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
29890 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
298a0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
298b0 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
298c0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
298d0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
298e0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
298f0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
29900 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
29910 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
29920 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
29930 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
29940 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
29950 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
29960 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53  ction open..*/.S
29970 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
29980 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
29990 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
299a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
299b0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
299c0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
299d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
299e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
299f0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
29a00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
29a10 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
29a20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
29a30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
29a40 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
29a50 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
29a60 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
29a70 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
29a80 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
29a90 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
29aa0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
29ab0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
29ac0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
29ad0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29ae0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
29af0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
29b00 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
29b10 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
29b20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
29b30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29b40 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
29b50 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
29b60 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
29b70 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
29b80 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
29b90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29ba0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
29bb0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
29bc0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
29bd0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
29be0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
29bf0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
29c00 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
29c10 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
29c20 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
29c30 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
29c40 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
29c50 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
29c60 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
29c70 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
29c80 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
29c90 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
29ca0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
29cb0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
29cc0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
29cd0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
29ce0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
29cf0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
29d00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29d10 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
29d20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
29d30 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
29d40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
29d50 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
29d60 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
29d70 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
29d80 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
29d90 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
29da0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
29db0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
29dc0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
29dd0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
29de0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
29df0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
29e00 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
29e10 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
29e20 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
29e30 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
29e40 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
29e50 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
29e60 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
29e70 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
29e80 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
29e90 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
29ea0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
29eb0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
29ec0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
29ed0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
29ee0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
29ef0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
29f00 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
29f10 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
29f20 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
29f30 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
29f40 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
29f50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
29f60 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
29f70 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
29f80 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
29f90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
29fa0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
29fb0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
29fc0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
29fd0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
29fe0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
29ff0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2a000 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
2a010 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
2a020 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2a030 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2a040 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2a050 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2a060 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
2a070 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
2a080 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2a090 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
2a0a0 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
2a0b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2a0c0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2a0d0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2a0e0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
2a0f0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
2a100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
2a110 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
2a120 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
2a130 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
2a140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2a150 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
2a160 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
2a170 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
2a180 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
2a190 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2a1a0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2a1b0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
2a1c0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
2a1d0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
2a1e0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
2a1f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2a200 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
2a210 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
2a220 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2a230 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
2a240 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
2a250 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2a260 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2a270 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
2a280 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2a290 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2a2a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
2a2b0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
2a2c0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
2a2d0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
2a2e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2a2f0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
2a300 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2a310 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2a320 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
2a330 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
2a340 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2a350 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
2a360 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
2a370 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
2a380 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
2a390 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
2a3a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2a3b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
2a3c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
2a3d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2a3e0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
2a3f0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
2a400 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
2a410 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
2a420 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
2a430 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
2a440 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
2a450 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
2a460 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
2a470 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
2a480 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
2a490 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
2a4a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
2a4b0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
2a4c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2a4d0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
2a4e0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
2a4f0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
2a500 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
2a510 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
2a520 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
2a530 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
2a540 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
2a550 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
2a560 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
2a570 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
2a580 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
2a590 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
2a5a0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
2a5b0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
2a5c0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
2a5d0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
2a5e0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
2a5f0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
2a600 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
2a610 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
2a620 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
2a630 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
2a640 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
2a650 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
2a660 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
2a670 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
2a680 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2a690 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
2a6a0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
2a6b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2a6c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
2a6d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2a6e0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
2a6f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
2a700 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2a710 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
2a720 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
2a730 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
2a740 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
2a750 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2a760 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2a770 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
2a780 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
2a790 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
2a7a0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
2a7b0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2a7c0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
2a7d0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
2a7e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
2a7f0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
2a800 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
2a810 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
2a820 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
2a830 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
2a840 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
2a850 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
2a860 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
2a870 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
2a880 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
2a890 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
2a8a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a8b0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
2a8c0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
2a8d0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
2a8e0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
2a8f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
2a900 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
2a910 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
2a920 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
2a930 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2a940 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
2a950 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2a960 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
2a970 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
2a980 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
2a990 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2a9a0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
2a9b0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
2a9c0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
2a9d0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
2a9e0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
2a9f0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
2aa00 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2aa10 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2aa20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
2aa30 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
2aa40 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
2aa50 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
2aa60 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
2aa70 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
2aa80 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2aa90 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
2aaa0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2aab0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
2aac0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
2aad0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
2aae0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2aaf0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
2ab00 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
2ab10 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ator..** If a no
2ab20 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
2ab30 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
2ab40 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
2ab50 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
2ab60 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
2ab70 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20  d_text16() then 
2ab80 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
2ab90 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
2aba0 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
2abb0 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
2abc0 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
2abd0 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
2abe0 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
2abf0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
2ac00 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
2ac10 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
2ac20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
2ac30 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
2ac40 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
2ac50 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
2ac60 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
2ac70 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
2ac80 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
2ac90 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
2aca0 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
2acb0 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
2acc0 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
2acd0 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
2ace0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2acf0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
2ad00 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
2ad10 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
2ad20 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
2ad30 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
2ad40 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
2ad50 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
2ad60 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
2ad70 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
2ad80 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
2ad90 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
2ada0 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
2adb0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
2adc0 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
2add0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
2ade0 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
2adf0 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  he call to sqlit
2ae00 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a  e3_bind_blob(),.
2ae10 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
2ae20 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74  text(), or sqlit
2ae30 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
2ae40 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66   fails.  .** ^If
2ae50 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2ae60 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
2ae70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
2ae80 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
2ae90 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
2aea0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
2aeb0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
2aec0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
2aed0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
2aee0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
2aef0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
2af00 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2af10 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
2af20 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
2af30 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
2af40 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
2af50 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
2af60 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
2af70 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
2af80 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
2af90 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
2afa0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
2afb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
2afc0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
2afd0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
2afe0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
2aff0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
2b000 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
2b010 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
2b020 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
2b030 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
2b040 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
2b050 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
2b060 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
2b070 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
2b080 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
2b090 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
2b0a0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
2b0b0 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
2b0c0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
2b0d0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
2b0e0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
2b0f0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
2b100 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
2b110 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
2b120 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
2b130 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
2b140 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
2b150 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
2b160 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
2b170 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2b180 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2b190 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
2b1a0 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
2b1b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2b1c0 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
2b1d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b1e0 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
2b1f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2b200 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
2b210 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
2b220 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
2b230 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
2b240 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
2b250 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
2b260 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
2b270 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
2b280 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
2b290 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
2b2a0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
2b2b0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2b2c0 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
2b2d0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
2b2e0 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
2b2f0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
2b300 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
2b310 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
2b320 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
2b330 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
2b340 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
2b350 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
2b360 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
2b370 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
2b380 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
2b390 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
2b3a0 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
2b3b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
2b3c0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
2b3d0 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
2b3e0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
2b3f0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
2b400 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
2b410 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
2b420 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
2b430 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
2b440 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
2b450 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2b460 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2b470 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
2b480 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2b490 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2b4a0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
2b4b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2b4c0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2b4d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2b4e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
2b4f0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b500 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2b510 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
2b520 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2b530 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2b540 6e 64 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  nd_double(sqlite
2b550 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f  3_stmt*, int, do
2b560 75 62 6c 65 29 3b 0a 53 51 4c 49 54 45 5f 41 50  uble);.SQLITE_AP
2b570 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2b580 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
2b590 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
2b5a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b5b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2b5c0 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  64(sqlite3_stmt*
2b5d0 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69  , int, sqlite3_i
2b5e0 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt64);.SQLITE_AP
2b5f0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2b600 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  nd_null(sqlite3_
2b610 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  stmt*, int);.SQL
2b620 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2b630 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
2b640 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2b650 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
2b660 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
2b670 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
2b680 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2b690 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  nd_text16(sqlite
2b6a0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b6b0 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20  nst void*, int, 
2b6c0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2b6d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b6e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2b6f0 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ue(sqlite3_stmt*
2b700 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 73 71 6c  , int, const sql
2b710 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
2b720 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2b730 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c  ite3_bind_zerobl
2b740 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
2b750 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a  , int, int n);..
2b760 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2b770 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61  Number Of SQL Pa
2b780 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e  rameters.**.** ^
2b790 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e  This routine can
2b7a0 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64   be used to find
2b7b0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b   the number of [
2b7c0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a  SQL parameters].
2b7d0 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65  ** in a [prepare
2b7e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53  d statement].  S
2b7f0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  QL parameters ar
2b800 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a  e tokens of the.
2b810 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e  ** form "?", "?N
2b820 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41  NN", ":AAA", "$A
2b830 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74  AA", or "@AAA" t
2b840 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20  hat serve as.** 
2b850 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2b860 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65   values that are
2b870 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2b880 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20  lob | bound].** 
2b890 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
2b8a0 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d  s at a later tim
2b8b0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20  e..**.** ^(This 
2b8c0 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79  routine actually
2b8d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64   returns the ind
2b8e0 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ex of the larges
2b8f0 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a  t (rightmost).**
2b900 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20   parameter. For 
2b910 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74  all forms except
2b920 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c   ?NNN, this will
2b930 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74   correspond to t
2b940 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
2b950 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72  unique parameter
2b960 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72  s.  If parameter
2b970 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f  s of the ?NNN fo
2b980 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20  rm are used,.** 
2b990 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70  there may be gap
2b9a0 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e  s in the list.)^
2b9b0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2b9c0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2b9d0 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2b9e0 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
2b9f0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2ba00 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  name()], and.** 
2ba10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2ba20 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2ba30 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2ba40 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2ba50 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
2ba60 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
2ba70 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2ba80 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73 74  : Name Of A Host
2ba90 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a   Parameter.**.**
2baa0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69   ^The sqlite3_bi
2bab0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2bac0 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63 65  e(P,N) interface
2bad0 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2bae0 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74 68  name of the N-th
2baf0 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
2bb00 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65   in the [prepare
2bb10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a  d statement] P..
2bb20 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65 74  ** ^(SQL paramet
2bb30 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d 20  ers of the form 
2bb40 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22  "?NNN" or ":AAA"
2bb50 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22 24   or "@AAA" or "$
2bb60 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e  AAA".** have a n
2bb70 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68 65  ame which is the
2bb80 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f   string "?NNN" o
2bb90 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41  r ":AAA" or "@AA
2bba0 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20  A" or "$AAA".** 
2bbb0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
2bbc0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
2bbd0 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a 22   the initial ":"
2bbe0 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20 6f   or "$" or "@" o
2bbf0 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c  r "?".** is incl
2bc00 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  uded as part of 
2bc10 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e  the name.)^.** ^
2bc20 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68  Parameters of th
2bc30 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f  e form "?" witho
2bc40 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69  ut a following i
2bc50 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20 6e  nteger have no n
2bc60 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72  ame.** and are r
2bc70 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22 6e  eferred to as "n
2bc80 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f  ameless" or "ano
2bc90 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65 72  nymous parameter
2bca0 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  s"..**.** ^The f
2bcb0 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d 65  irst host parame
2bcc0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2bcd0 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a   of 1, not 0..**
2bce0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c 75  .** ^If the valu
2bcf0 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61  e N is out of ra
2bd00 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e 2d  nge or if the N-
2bd10 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a  th parameter is.
2bd20 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68 65  ** nameless, the
2bd30 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72 6e  n NULL is return
2bd40 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
2bd50 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  ed string is.** 
2bd60 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38 20  always in UTF-8 
2bd70 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69 66  encoding even if
2bd80 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61 6d   the named param
2bd90 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69 67  eter was.** orig
2bda0 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65 64  inally specified
2bdb0 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b 73   as UTF-16 in [s
2bdc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2bdd0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
2bde0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
2bdf0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  )]..**.** See al
2be00 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  so: [sqlite3_bin
2be10 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62  d_blob|sqlite3_b
2be20 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  ind()],.** [sqli
2be30 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2be40 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64  er_count()], and
2be50 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2be60 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2be70 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
2be80 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2be90 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2bea0 61 6d 65 74 65 72 5f 6e 61 6d 65 28 73 71 6c 69  ameter_name(sqli
2beb0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2bec0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2bed0 3a 20 49 6e 64 65 78 20 4f 66 20 41 20 50 61 72  : Index Of A Par
2bee0 61 6d 65 74 65 72 20 57 69 74 68 20 41 20 47 69  ameter With A Gi
2bef0 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e  ven Name.**.** ^
2bf00 52 65 74 75 72 6e 20 74 68 65 20 69 6e 64 65 78  Return the index
2bf10 20 6f 66 20 61 6e 20 53 51 4c 20 70 61 72 61 6d   of an SQL param
2bf20 65 74 65 72 20 67 69 76 65 6e 20 69 74 73 20 6e  eter given its n
2bf30 61 6d 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 69 6e  ame.  ^The.** in
2bf40 64 65 78 20 76 61 6c 75 65 20 72 65 74 75 72 6e  dex value return
2bf50 65 64 20 69 73 20 73 75 69 74 61 62 6c 65 20 66  ed is suitable f
2bf60 6f 72 20 75 73 65 20 61 73 20 74 68 65 20 73 65  or use as the se
2bf70 63 6f 6e 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  cond.** paramete
2bf80 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 62 69  r to [sqlite3_bi
2bf90 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2bfa0 62 69 6e 64 28 29 5d 2e 20 20 5e 41 20 7a 65 72  bind()].  ^A zer
2bfb0 6f 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64  o.** is returned
2bfc0 20 69 66 20 6e 6f 20 6d 61 74 63 68 69 6e 67 20   if no matching 
2bfd0 70 61 72 61 6d 65 74 65 72 20 69 73 20 66 6f 75  parameter is fou
2bfe0 6e 64 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65  nd.  ^The parame
2bff0 74 65 72 0a 2a 2a 20 6e 61 6d 65 20 6d 75 73 74  ter.** name must
2c000 20 62 65 20 67 69 76 65 6e 20 69 6e 20 55 54 46   be given in UTF
2c010 2d 38 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f  -8 even if the o
2c020 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
2c030 74 0a 2a 2a 20 77 61 73 20 70 72 65 70 61 72 65  t.** was prepare
2c040 64 20 66 72 6f 6d 20 55 54 46 2d 31 36 20 74 65  d from UTF-16 te
2c050 78 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  xt using [sqlite
2c060 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2c070 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  ]..**.** See als
2c080 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  o: [sqlite3_bind
2c090 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69  _blob|sqlite3_bi
2c0a0 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  nd()],.** [sqlit
2c0b0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2c0c0 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a  r_count()], and.
2c0d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2c0e0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2c0f0 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
2c100 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2c110 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2c120 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
2c130 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2c140 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
2c150 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
2c160 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
2c170 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2c180 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  nt.**.** ^Contra
2c190 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
2c1a0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
2c1b0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
2c1c0 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
2c1d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2c1e0 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
2c1f0 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
2c200 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2c210 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
2c220 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
2c230 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2c240 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c   to NULL..*/.SQL
2c250 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2c260 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2c270 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2c280 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c290 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2c2a0 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2c2b0 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
2c2c0 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
2c2d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2c2e0 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
2c2f0 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
2c300 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2c310 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
2c320 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2c330 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
2c340 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
2c350 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
2c360 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
2c370 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2c380 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2c390 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
2c3a0 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49  count()].*/.SQLI
2c3b0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c3c0 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28  e3_column_count(
2c3d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53  sqlite3_stmt *pS
2c3e0 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tmt);../*.** CAP
2c3f0 49 33 52 45 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61  I3REF: Column Na
2c400 6d 65 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20  mes In A Result 
2c410 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  Set.**.** ^These
2c420 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c430 20 74 68 65 20 6e 61 6d 65 20 61 73 73 69 67 6e   the name assign
2c440 65 64 20 74 6f 20 61 20 70 61 72 74 69 63 75 6c  ed to a particul
2c450 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20  ar column.** in 
2c460 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f  the result set o
2c470 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  f a [SELECT] sta
2c480 74 65 6d 65 6e 74 2e 20 20 5e 54 68 65 20 73 71  tement.  ^The sq
2c490 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2c4a0 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  e().** interface
2c4b0 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2c4c0 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72  er to a zero-ter
2c4d0 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74  minated UTF-8 st
2c4e0 72 69 6e 67 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ring.** and sqli
2c4f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2c500 36 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  6() returns a po
2c510 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f 2d  inter to a zero-
2c520 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54  terminated.** UT
2c530 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54  F-16 string.  ^T
2c540 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2c550 65 72 20 69 73 20 74 68 65 20 5b 70 72 65 70 61  er is the [prepa
2c560 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
2c570 2a 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  * that implement
2c580 73 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73  s the [SELECT] s
2c590 74 61 74 65 6d 65 6e 74 2e 20 5e 54 68 65 20 73  tatement. ^The s
2c5a0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
2c5b0 69 73 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e  is the.** column
2c5c0 20 6e 75 6d 62 65 72 2e 20 20 5e 54 68 65 20 6c   number.  ^The l
2c5d0 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69  eftmost column i
2c5e0 73 20 6e 75 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a  s number 0..**.*
2c5f0 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20  * ^The returned 
2c600 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 69  string pointer i
2c610 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 65 69  s valid until ei
2c620 74 68 65 72 20 74 68 65 20 5b 70 72 65 70 61 72  ther the [prepar
2c630 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a  ed statement].**
2c640 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 62 79   is destroyed by
2c650 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2c660 7a 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74  ze()] or until t
2c670 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
2c680 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
2c690 20 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74   reprepared by t
2c6a0 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f  he first call to
2c6b0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2c6c0 5d 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  ] for a particul
2c6d0 61 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74  ar run.** or unt
2c6e0 69 6c 20 74 68 65 20 6e 65 78 74 20 63 61 6c 6c  il the next call
2c6f0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2c700 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 20 6f 72 20  olumn_name() or 
2c710 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2c720 61 6d 65 31 36 28 29 20 6f 6e 20 74 68 65 20 73  ame16() on the s
2c730 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a  ame column..**.*
2c740 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61  * ^If sqlite3_ma
2c750 6c 6c 6f 63 28 29 20 66 61 69 6c 73 20 64 75 72  lloc() fails dur
2c760 69 6e 67 20 74 68 65 20 70 72 6f 63 65 73 73 69  ing the processi
2c770 6e 67 20 6f 66 20 65 69 74 68 65 72 20 72 6f 75  ng of either rou
2c780 74 69 6e 65 0a 2a 2a 20 28 66 6f 72 20 65 78 61  tine.** (for exa
2c790 6d 70 6c 65 20 64 75 72 69 6e 67 20 61 20 63 6f  mple during a co
2c7a0 6e 76 65 72 73 69 6f 6e 20 66 72 6f 6d 20 55 54  nversion from UT
2c7b0 46 2d 38 20 74 6f 20 55 54 46 2d 31 36 29 20 74  F-8 to UTF-16) t
2c7c0 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f  hen a.** NULL po
2c7d0 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65  inter is returne
2c7e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  d..**.** ^The na
2c7f0 6d 65 20 6f 66 20 61 20 72 65 73 75 6c 74 20 63  me of a result c
2c800 6f 6c 75 6d 6e 20 69 73 20 74 68 65 20 76 61 6c  olumn is the val
2c810 75 65 20 6f 66 20 74 68 65 20 22 41 53 22 20 63  ue of the "AS" c
2c820 6c 61 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 61  lause for.** tha
2c830 74 20 63 6f 6c 75 6d 6e 2c 20 69 66 20 74 68 65  t column, if the
2c840 72 65 20 69 73 20 61 6e 20 41 53 20 63 6c 61 75  re is an AS clau
2c850 73 65 2e 20 20 49 66 20 74 68 65 72 65 20 69 73  se.  If there is
2c860 20 6e 6f 20 41 53 20 63 6c 61 75 73 65 0a 2a 2a   no AS clause.**
2c870 20 74 68 65 6e 20 74 68 65 20 6e 61 6d 65 20 6f   then the name o
2c880 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 69 73 20  f the column is 
2c890 75 6e 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  unspecified and 
2c8a0 6d 61 79 20 63 68 61 6e 67 65 20 66 72 6f 6d 0a  may change from.
2c8b0 2a 2a 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 6f  ** one release o
2c8c0 66 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  f SQLite to the 
2c8d0 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  next..*/.SQLITE_
2c8e0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2c8f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2c900 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2c910 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54  *, int N);.SQLIT
2c920 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2c930 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2c940 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2c950 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
2c960 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c970 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
2c980 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
2c990 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2c9a0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
2c9b0 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
2c9c0 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
2c9d0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
2c9e0 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
2c9f0 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
2ca00 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
2ca10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
2ca20 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
2ca30 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
2ca40 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
2ca50 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
2ca60 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
2ca70 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
2ca80 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
2ca90 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
2caa0 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
2cab0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
2cac0 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
2cad0 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
2cae0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
2caf0 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
2cb00 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
2cb10 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
2cb20 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
2cb30 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
2cb40 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2cb50 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
2cb60 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2cb70 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
2cb80 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
2cb90 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2cba0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
2cbb0 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
2cbc0 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
2cbd0 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
2cbe0 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
2cbf0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
2cc00 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
2cc10 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
2cc20 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
2cc30 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
2cc40 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
2cc50 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
2cc60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
2cc70 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
2cc80 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
2cc90 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
2cca0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
2ccb0 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
2ccc0 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
2ccd0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2cce0 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
2ccf0 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
2cd00 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2cd10 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2cd20 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2cd30 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
2cd40 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
2cd50 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2cd60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
2cd70 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
2cd80 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
2cd90 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
2cda0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
2cdb0 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
2cdc0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
2cdd0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
2cde0 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
2cdf0 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
2ce00 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
2ce10 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
2ce20 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
2ce30 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
2ce40 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
2ce50 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
2ce60 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
2ce70 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
2ce80 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
2ce90 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
2cea0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
2ceb0 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
2cec0 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
2ced0 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
2cee0 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
2cef0 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
2cf00 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
2cf10 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
2cf20 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
2cf30 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
2cf40 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
2cf50 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
2cf60 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
2cf70 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
2cf80 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
2cf90 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
2cfa0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
2cfb0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
2cfc0 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
2cfd0 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
2cfe0 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
2cff0 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
2d000 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
2d010 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
2d020 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
2d030 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
2d040 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
2d050 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2d060 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2d070 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
2d080 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
2d090 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
2d0a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
2d0b0 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
2d0c0 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
2d0d0 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
2d0e0 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
2d0f0 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
2d100 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
2d110 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
2d120 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2d130 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
2d140 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
2d150 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
2d160 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
2d170 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d180 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
2d190 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
2d1a0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
2d1b0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2d1c0 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ined..*/.SQLITE_
2d1d0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2d1e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2d1f0 61 74 61 62 61 73 65 5f 6e 61 6d 65 28 73 71 6c  atabase_name(sql
2d200 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2d210 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2d220 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2d230 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f  column_database_
2d240 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2d250 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2d260 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2d270 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2d280 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2d290 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2d2a0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
2d2b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2d2c0 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65  olumn_table_name
2d2d0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2d2e0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2d2f0 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2d300 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2d310 67 69 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  gin_name(sqlite3
2d320 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2d330 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2d340 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2d350 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
2d360 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2d370 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2d380 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
2d390 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
2d3a0 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
2d3b0 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
2d3c0 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
2d3d0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2d3e0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
2d3f0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
2d400 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
2d410 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
2d420 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
2d430 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
2d440 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
2d450 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
2d460 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
2d470 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2d480 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
2d490 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
2d4a0 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
2d4b0 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
2d4c0 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
2d4d0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
2d4e0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
2d4f0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2d500 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
2d510 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2d520 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
2d530 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2d540 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
2d550 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
2d560 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
2d570 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
2d580 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
2d590 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
2d5a0 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
2d5b0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
2d5c0 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
2d5d0 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
2d5e0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
2d5f0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
2d600 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
2d610 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
2d620 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
2d630 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
2d640 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
2d650 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
2d660 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
2d670 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
2d680 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
2d690 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
2d6a0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
2d6b0 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
2d6c0 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
2d6d0 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
2d6e0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
2d6f0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
2d700 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
2d710 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
2d720 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
2d730 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
2d740 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
2d750 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
2d760 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
2d770 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
2d780 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
2d790 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
2d7a0 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
2d7b0 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
2d7c0 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
2d7d0 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
2d7e0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
2d7f0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
2d800 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2d810 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2d820 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74  te3_column_declt
2d830 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ype(sqlite3_stmt
2d840 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  *,int);.SQLITE_A
2d850 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
2d860 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
2d870 63 6c 74 79 70 65 31 36 28 73 71 6c 69 74 65 33  cltype16(sqlite3
2d880 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a  _stmt*,int);../*
2d890 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 76  .** CAPI3REF: Ev
2d8a0 61 6c 75 61 74 65 20 41 6e 20 53 51 4c 20 53 74  aluate An SQL St
2d8b0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66  atement.**.** Af
2d8c0 74 65 72 20 61 20 5b 70 72 65 70 61 72 65 64 20  ter a [prepared 
2d8d0 73 74 61 74 65 6d 65 6e 74 5d 20 68 61 73 20 62  statement] has b
2d8e0 65 65 6e 20 70 72 65 70 61 72 65 64 20 75 73 69  een prepared usi
2d8f0 6e 67 20 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  ng either.** [sq
2d900 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2d910 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2d920 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2d930 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 65  or one of the le
2d940 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63  gacy.** interfac
2d950 65 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  es [sqlite3_prep
2d960 61 72 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  are()] or [sqlit
2d970 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2c  e3_prepare16()],
2d980 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 0a 2a   this function.*
2d990 2a 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  * must be called
2d9a0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
2d9b0 65 73 20 74 6f 20 65 76 61 6c 75 61 74 65 20 74  es to evaluate t
2d9c0 68 65 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  he statement..**
2d9d0 0a 2a 2a 20 54 68 65 20 64 65 74 61 69 6c 73 20  .** The details 
2d9e0 6f 66 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  of the behavior 
2d9f0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  of the sqlite3_s
2da00 74 65 70 28 29 20 69 6e 74 65 72 66 61 63 65 20  tep() interface 
2da10 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65  depend.** on whe
2da20 74 68 65 72 20 74 68 65 20 73 74 61 74 65 6d 65  ther the stateme
2da30 6e 74 20 77 61 73 20 70 72 65 70 61 72 65 64 20  nt was prepared 
2da40 75 73 69 6e 67 20 74 68 65 20 6e 65 77 65 72 20  using the newer 
2da50 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 0a 2a  "v2" interface.*
2da60 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
2da70 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
2da80 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2da90 76 32 28 29 5d 20 6f 72 20 74 68 65 20 6f 6c 64  v2()] or the old
2daa0 65 72 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74  er legacy.** int
2dab0 65 72 66 61 63 65 20 5b 73 71 6c 69 74 65 33 5f  erface [sqlite3_
2dac0 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
2dad0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2dae0 36 28 29 5d 2e 20 20 54 68 65 20 75 73 65 20 6f  6()].  The use o
2daf0 66 20 74 68 65 0a 2a 2a 20 6e 65 77 20 22 76 32  f the.** new "v2
2db00 22 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 72  " interface is r
2db10 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6e  ecommended for n
2db20 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
2db30 62 75 74 20 74 68 65 20 6c 65 67 61 63 79 0a 2a  but the legacy.*
2db40 2a 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c  * interface will
2db50 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 20   continue to be 
2db60 73 75 70 70 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a  supported..**.**
2db70 20 5e 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20   ^In the legacy 
2db80 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 72  interface, the r
2db90 65 74 75 72 6e 20 76 61 6c 75 65 20 77 69 6c 6c  eturn value will
2dba0 20 62 65 20 65 69 74 68 65 72 20 5b 53 51 4c 49   be either [SQLI
2dbb0 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51  TE_BUSY],.** [SQ
2dbc0 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c  LITE_DONE], [SQL
2dbd0 49 54 45 5f 52 4f 57 5d 2c 20 5b 53 51 4c 49 54  ITE_ROW], [SQLIT
2dbe0 45 5f 45 52 52 4f 52 5d 2c 20 6f 72 20 5b 53 51  E_ERROR], or [SQ
2dbf0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a  LITE_MISUSE]..**
2dc00 20 5e 57 69 74 68 20 74 68 65 20 22 76 32 22 20   ^With the "v2" 
2dc10 69 6e 74 65 72 66 61 63 65 2c 20 61 6e 79 20 6f  interface, any o
2dc20 66 20 74 68 65 20 6f 74 68 65 72 20 5b 72 65 73  f the other [res
2dc30 75 6c 74 20 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a  ult codes] or.**
2dc40 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
2dc50 74 20 63 6f 64 65 73 5d 20 6d 69 67 68 74 20 62  t codes] might b
2dc60 65 20 72 65 74 75 72 6e 65 64 20 61 73 20 77 65  e returned as we
2dc70 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ll..**.** ^[SQLI
2dc80 54 45 5f 42 55 53 59 5d 20 6d 65 61 6e 73 20 74  TE_BUSY] means t
2dc90 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
2dca0 20 65 6e 67 69 6e 65 20 77 61 73 20 75 6e 61 62   engine was unab
2dcb0 6c 65 20 74 6f 20 61 63 71 75 69 72 65 20 74 68  le to acquire th
2dcc0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 6c 6f  e.** database lo
2dcd0 63 6b 73 20 69 74 20 6e 65 65 64 73 20 74 6f 20  cks it needs to 
2dce0 64 6f 20 69 74 73 20 6a 6f 62 2e 20 20 5e 49 66  do its job.  ^If
2dcf0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2dd00 73 20 61 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  s a [COMMIT].** 
2dd10 6f 72 20 6f 63 63 75 72 73 20 6f 75 74 73 69 64  or occurs outsid
2dd20 65 20 6f 66 20 61 6e 20 65 78 70 6c 69 63 69 74  e of an explicit
2dd30 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68   transaction, th
2dd40 65 6e 20 79 6f 75 20 63 61 6e 20 72 65 74 72 79  en you can retry
2dd50 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   the.** statemen
2dd60 74 2e 20 20 49 66 20 74 68 65 20 73 74 61 74 65  t.  If the state
2dd70 6d 65 6e 74 20 69 73 20 6e 6f 74 20 61 20 5b 43  ment is not a [C
2dd80 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f 63 63 75 72  OMMIT] and occur
2dd90 73 20 77 69 74 68 69 6e 20 61 6e 0a 2a 2a 20 65  s within an.** e
2dda0 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2ddb0 69 6f 6e 20 74 68 65 6e 20 79 6f 75 20 73 68 6f  ion then you sho
2ddc0 75 6c 64 20 72 6f 6c 6c 62 61 63 6b 20 74 68 65  uld rollback the
2ddd0 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62 65 66   transaction bef
2dde0 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e  ore.** continuin
2ddf0 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  g..**.** ^[SQLIT
2de00 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e 73 20 74 68  E_DONE] means th
2de10 61 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  at the statement
2de20 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 65 78   has finished ex
2de30 65 63 75 74 69 6e 67 0a 2a 2a 20 73 75 63 63 65  ecuting.** succe
2de40 73 73 66 75 6c 6c 79 2e 20 20 73 71 6c 69 74 65  ssfully.  sqlite
2de50 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20  3_step() should 
2de60 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67  not be called ag
2de70 61 69 6e 20 6f 6e 20 74 68 69 73 20 76 69 72 74  ain on this virt
2de80 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 77  ual.** machine w
2de90 69 74 68 6f 75 74 20 66 69 72 73 74 20 63 61 6c  ithout first cal
2dea0 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  ling [sqlite3_re
2deb0 73 65 74 28 29 5d 20 74 6f 20 72 65 73 65 74 20  set()] to reset 
2dec0 74 68 65 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  the virtual.** m
2ded0 61 63 68 69 6e 65 20 62 61 63 6b 20 74 6f 20 69  achine back to i
2dee0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2def0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2df00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 62 65  SQL statement be
2df10 69 6e 67 20 65 78 65 63 75 74 65 64 20 72 65 74  ing executed ret
2df20 75 72 6e 73 20 61 6e 79 20 64 61 74 61 2c 20 74  urns any data, t
2df30 68 65 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  hen [SQLITE_ROW]
2df40 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20  .** is returned 
2df50 65 61 63 68 20 74 69 6d 65 20 61 20 6e 65 77 20  each time a new 
2df60 72 6f 77 20 6f 66 20 64 61 74 61 20 69 73 20 72  row of data is r
2df70 65 61 64 79 20 66 6f 72 20 70 72 6f 63 65 73 73  eady for process
2df80 69 6e 67 20 62 79 20 74 68 65 0a 2a 2a 20 63 61  ing by the.** ca
2df90 6c 6c 65 72 2e 20 54 68 65 20 76 61 6c 75 65 73  ller. The values
2dfa0 20 6d 61 79 20 62 65 20 61 63 63 65 73 73 65 64   may be accessed
2dfb0 20 75 73 69 6e 67 20 74 68 65 20 5b 63 6f 6c 75   using the [colu
2dfc0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2dfd0 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c 69 74 65 33  ons]..** sqlite3
2dfe0 5f 73 74 65 70 28 29 20 69 73 20 63 61 6c 6c 65  _step() is calle
2dff0 64 20 61 67 61 69 6e 20 74 6f 20 72 65 74 72 69  d again to retri
2e000 65 76 65 20 74 68 65 20 6e 65 78 74 20 72 6f 77  eve the next row
2e010 20 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20   of data..**.** 
2e020 5e 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20  ^[SQLITE_ERROR] 
2e030 6d 65 61 6e 73 20 74 68 61 74 20 61 20 72 75 6e  means that a run
2e040 2d 74 69 6d 65 20 65 72 72 6f 72 20 28 73 75 63  -time error (suc
2e050 68 20 61 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  h as a constrain
2e060 74 0a 2a 2a 20 76 69 6f 6c 61 74 69 6f 6e 29 20  t.** violation) 
2e070 68 61 73 20 6f 63 63 75 72 72 65 64 2e 20 20 73  has occurred.  s
2e080 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68  qlite3_step() sh
2e090 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c  ould not be call
2e0a0 65 64 20 61 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74  ed again on.** t
2e0b0 68 65 20 56 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f  he VM. More info
2e0c0 72 6d 61 74 69 6f 6e 20 6d 61 79 20 62 65 20 66  rmation may be f
2e0d0 6f 75 6e 64 20 62 79 20 63 61 6c 6c 69 6e 67 20  ound by calling 
2e0e0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28  [sqlite3_errmsg(
2e0f0 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65  )]..** ^With the
2e100 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
2e110 65 2c 20 61 20 6d 6f 72 65 20 73 70 65 63 69 66  e, a more specif
2e120 69 63 20 65 72 72 6f 72 20 63 6f 64 65 20 28 66  ic error code (f
2e130 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b  or example,.** [
2e140 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
2e150 5d 2c 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ], [SQLITE_SCHEM
2e160 41 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52  A], [SQLITE_CORR
2e170 55 50 54 5d 2c 20 61 6e 64 20 73 6f 20 66 6f 72  UPT], and so for
2e180 74 68 29 0a 2a 2a 20 63 61 6e 20 62 65 20 6f 62  th).** can be ob
2e190 74 61 69 6e 65 64 20 62 79 20 63 61 6c 6c 69 6e  tained by callin
2e1a0 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
2e1b0 28 29 5d 20 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70  ()] on the.** [p
2e1c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2e1d0 74 5d 2e 20 20 5e 49 6e 20 74 68 65 20 22 76 32  t].  ^In the "v2
2e1e0 22 20 69 6e 74 65 72 66 61 63 65 2c 0a 2a 2a 20  " interface,.** 
2e1f0 74 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69  the more specifi
2e200 63 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  c error code is 
2e210 72 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c  returned directl
2e220 79 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  y by sqlite3_ste
2e230 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49  p()..**.** [SQLI
2e240 54 45 5f 4d 49 53 55 53 45 5d 20 6d 65 61 6e 73  TE_MISUSE] means
2e250 20 74 68 61 74 20 74 68 65 20 74 68 69 73 20 72   that the this r
2e260 6f 75 74 69 6e 65 20 77 61 73 20 63 61 6c 6c 65  outine was calle
2e270 64 20 69 6e 61 70 70 72 6f 70 72 69 61 74 65 6c  d inappropriatel
2e280 79 2e 0a 2a 2a 20 50 65 72 68 61 70 73 20 69 74  y..** Perhaps it
2e290 20 77 61 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61   was called on a
2e2a0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2e2b0 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73 0a 2a  ment] that has.*
2e2c0 2a 20 61 6c 72 65 61 64 79 20 62 65 65 6e 20 5b  * already been [
2e2d0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2e2e0 20 7c 20 66 69 6e 61 6c 69 7a 65 64 5d 20 6f 72   | finalized] or
2e2f0 20 6f 6e 20 6f 6e 65 20 74 68 61 74 20 68 61 64   on one that had
2e300 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 72  .** previously r
2e310 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2e320 45 52 52 4f 52 5d 20 6f 72 20 5b 53 51 4c 49 54  ERROR] or [SQLIT
2e330 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72 20 69 74 20  E_DONE].  Or it 
2e340 63 6f 75 6c 64 0a 2a 2a 20 62 65 20 74 68 65 20  could.** be the 
2e350 63 61 73 65 20 74 68 61 74 20 74 68 65 20 73 61  case that the sa
2e360 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
2e370 65 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  ection is being 
2e380 75 73 65 64 20 62 79 20 74 77 6f 20 6f 72 0a 2a  used by two or.*
2e390 2a 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 61  * more threads a
2e3a0 74 20 74 68 65 20 73 61 6d 65 20 6d 6f 6d 65 6e  t the same momen
2e3b0 74 20 69 6e 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  t in time..**.**
2e3c0 20 46 6f 72 20 61 6c 6c 20 76 65 72 73 69 6f 6e   For all version
2e3d0 73 20 6f 66 20 53 51 4c 69 74 65 20 75 70 20 74  s of SQLite up t
2e3e0 6f 20 61 6e 64 20 69 6e 63 6c 75 64 69 6e 67 20  o and including 
2e3f0 33 2e 36 2e 32 33 2e 31 2c 20 61 20 63 61 6c 6c  3.6.23.1, a call
2e400 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2e410 72 65 73 65 74 28 29 5d 20 77 61 73 20 72 65 71  reset()] was req
2e420 75 69 72 65 64 20 61 66 74 65 72 20 73 71 6c 69  uired after sqli
2e430 74 65 33 5f 73 74 65 70 28 29 20 72 65 74 75 72  te3_step() retur
2e440 6e 65 64 20 61 6e 79 74 68 69 6e 67 0a 2a 2a 20  ned anything.** 
2e450 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2e460 54 45 5f 52 4f 57 5d 20 62 65 66 6f 72 65 20 61  TE_ROW] before a
2e470 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ny subsequent in
2e480 76 6f 63 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73  vocation of.** s
2e490 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2e4a0 46 61 69 6c 75 72 65 20 74 6f 20 72 65 73 65 74  Failure to reset
2e4b0 20 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74   the prepared st
2e4c0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 0a 2a  atement using .*
2e4d0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2e4e0 28 29 5d 20 77 6f 75 6c 64 20 72 65 73 75 6c 74  ()] would result
2e4f0 20 69 6e 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4d   in an [SQLITE_M
2e500 49 53 55 53 45 5d 20 72 65 74 75 72 6e 20 66 72  ISUSE] return fr
2e510 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  om.** sqlite3_st
2e520 65 70 28 29 2e 20 20 42 75 74 20 61 66 74 65 72  ep().  But after
2e530 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 32 33 2e   version 3.6.23.
2e540 31 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  1, sqlite3_step(
2e550 29 20 62 65 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69  ) began.** calli
2e560 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
2e570 74 28 29 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c  t()] automatical
2e580 6c 79 20 69 6e 20 74 68 69 73 20 63 69 72 63 75  ly in this circu
2e590 6d 73 74 61 6e 63 65 20 72 61 74 68 65 72 0a 2a  mstance rather.*
2e5a0 2a 20 74 68 61 6e 20 72 65 74 75 72 6e 69 6e 67  * than returning
2e5b0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2e5c0 2e 20 20 54 68 69 73 20 69 73 20 6e 6f 74 20 63  .  This is not c
2e5d0 6f 6e 73 69 64 65 72 65 64 20 61 20 63 6f 6d 70  onsidered a comp
2e5e0 61 74 69 62 69 6c 69 74 79 0a 2a 2a 20 62 72 65  atibility.** bre
2e5f0 61 6b 20 62 65 63 61 75 73 65 20 61 6e 79 20 61  ak because any a
2e600 70 70 6c 69 63 61 74 69 6f 6e 20 74 68 61 74 20  pplication that 
2e610 65 76 65 72 20 72 65 63 65 69 76 65 73 20 61 6e  ever receives an
2e620 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 65   SQLITE_MISUSE e
2e630 72 72 6f 72 0a 2a 2a 20 69 73 20 62 72 6f 6b 65  rror.** is broke
2e640 6e 20 62 79 20 64 65 66 69 6e 69 74 69 6f 6e 2e  n by definition.
2e650 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d    The [SQLITE_OM
2e660 49 54 5f 41 55 54 4f 52 45 53 45 54 5d 20 63 6f  IT_AUTORESET] co
2e670 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
2e680 6e 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  n.** can be used
2e690 20 74 6f 20 72 65 73 74 6f 72 65 20 74 68 65 20   to restore the 
2e6a0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 2e  legacy behavior.
2e6b0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20  .**.** <b>Goofy 
2e6c0 49 6e 74 65 72 66 61 63 65 20 41 6c 65 72 74 3a  Interface Alert:
2e6d0 3c 2f 62 3e 20 49 6e 20 74 68 65 20 6c 65 67 61  </b> In the lega
2e6e0 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  cy interface, th
2e6f0 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  e sqlite3_step()
2e700 0a 2a 2a 20 41 50 49 20 61 6c 77 61 79 73 20 72  .** API always r
2e710 65 74 75 72 6e 73 20 61 20 67 65 6e 65 72 69 63  eturns a generic
2e720 20 65 72 72 6f 72 20 63 6f 64 65 2c 20 5b 53 51   error code, [SQ
2e730 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c  LITE_ERROR], fol
2e740 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a 2a 20 65 72  lowing any.** er
2e750 72 6f 72 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ror other than [
2e760 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 61 6e 64  SQLITE_BUSY] and
2e770 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2e780 2e 20 20 59 6f 75 20 6d 75 73 74 20 63 61 6c 6c  .  You must call
2e790 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2e7a0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2e7b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 6e  3_finalize()] in
2e7c0 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 6f   order to find o
2e7d0 6e 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 70 65  ne of the.** spe
2e7e0 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64  cific [error cod
2e7f0 65 73 5d 20 74 68 61 74 20 62 65 74 74 65 72 20  es] that better 
2e800 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
2e810 72 6f 72 2e 0a 2a 2a 20 57 65 20 61 64 6d 69 74  ror..** We admit
2e820 20 74 68 61 74 20 74 68 69 73 20 69 73 20 61 20   that this is a 
2e830 67 6f 6f 66 79 20 64 65 73 69 67 6e 2e 20 20 54  goofy design.  T
2e840 68 65 20 70 72 6f 62 6c 65 6d 20 68 61 73 20 62  he problem has b
2e850 65 65 6e 20 66 69 78 65 64 0a 2a 2a 20 77 69 74  een fixed.** wit
2e860 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  h the "v2" inter
2e870 66 61 63 65 2e 20 20 49 66 20 79 6f 75 20 70 72  face.  If you pr
2e880 65 70 61 72 65 20 61 6c 6c 20 6f 66 20 79 6f 75  epare all of you
2e890 72 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  r SQL statements
2e8a0 0a 2a 2a 20 75 73 69 6e 67 20 65 69 74 68 65 72  .** using either
2e8b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e8c0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2e8d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2e8e0 28 29 5d 20 69 6e 73 74 65 61 64 0a 2a 2a 20 6f  ()] instead.** o
2e8f0 66 20 74 68 65 20 6c 65 67 61 63 79 20 5b 73 71  f the legacy [sq
2e900 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2e910 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
2e920 65 70 61 72 65 31 36 28 29 5d 20 69 6e 74 65 72  epare16()] inter
2e930 66 61 63 65 73 2c 0a 2a 2a 20 74 68 65 6e 20 74  faces,.** then t
2e940 68 65 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63  he more specific
2e950 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 61   [error codes] a
2e960 72 65 20 72 65 74 75 72 6e 65 64 20 64 69 72 65  re returned dire
2e970 63 74 6c 79 0a 2a 2a 20 62 79 20 73 71 6c 69 74  ctly.** by sqlit
2e980 65 33 5f 73 74 65 70 28 29 2e 20 20 54 68 65 20  e3_step().  The 
2e990 75 73 65 20 6f 66 20 74 68 65 20 22 76 32 22 20  use of the "v2" 
2e9a0 69 6e 74 65 72 66 61 63 65 20 69 73 20 72 65 63  interface is rec
2e9b0 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c  ommended..*/.SQL
2e9c0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2e9d0 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33  te3_step(sqlite3
2e9e0 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  _stmt*);../*.** 
2e9f0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2ea00 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
2ea10 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a   result set.**.*
2ea20 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2ea30 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74  ata_count(P) int
2ea40 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
2ea50 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c  he number of col
2ea60 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63  umns in the.** c
2ea70 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68  urrent row of th
2ea80 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  e result set of 
2ea90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2eaa0 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70  ent] P..** ^If p
2eab0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2eac0 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76  t P does not hav
2ead0 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79 20  e results ready 
2eae0 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69  to return.** (vi
2eaf0 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b  a calls to the [
2eb00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2eb10 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt | sqlite3_col
2eb20 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69  umn_*()] of.** i
2eb30 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e 20  nterfaces) then 
2eb40 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2eb50 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e  nt(P) returns 0.
2eb60 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2eb70 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72  _data_count(P) r
2eb80 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75  outine also retu
2eb90 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61 20  rns 0 if P is a 
2eba0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2ebb0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
2ebc0 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
2ebd0 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
2ebe0 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63 61   the previous ca
2ebf0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2ec00 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2ec10 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ned [SQLITE_DONE
2ec20 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33  ].  ^The sqlite3
2ec30 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a  _data_count(P).*
2ec40 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f  * will return no
2ec50 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f  n-zero if previo
2ec60 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  us call to [sqli
2ec70 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74  te3_step](P) ret
2ec80 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45  urned.** [SQLITE
2ec90 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e  _ROW], except in
2eca0 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68 65   the case of the
2ecb0 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65   [PRAGMA increme
2ecc0 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20  ntal_vacuum].** 
2ecd0 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73 20  where it always 
2ece0 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e  returns zero sin
2ecf0 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66 20  ce each step of 
2ed00 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a  that multi-step.
2ed10 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e  ** pragma return
2ed20 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64  s 0 columns of d
2ed30 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ata..**.** See a
2ed40 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  lso: [sqlite3_co
2ed50 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  lumn_count()].*/
2ed60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ed70 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
2ed80 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  nt(sqlite3_stmt 
2ed90 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
2eda0 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61 6d  CAPI3REF: Fundam
2edb0 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73 0a  ental Datatypes.
2edc0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c  ** KEYWORDS: SQL
2edd0 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e  ITE_TEXT.**.** ^
2ede0 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e 20  (Every value in 
2edf0 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20 6f  SQLite has one o
2ee00 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e 74  f five fundament
2ee10 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a 2a  al datatypes:.**
2ee20 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
2ee30 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2ee40 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36  nteger.** <li> 6
2ee50 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61 74  4-bit IEEE float
2ee60 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72  ing point number
2ee70 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67 0a  .** <li> string.
2ee80 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20  ** <li> BLOB.** 
2ee90 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75  <li> NULL.** </u
2eea0 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  l>)^.**.** These
2eeb0 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 63   constants are c
2eec0 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f 66  odes for each of
2eed0 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a 2a   those types..**
2eee0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74 68  .** Note that th
2eef0 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63 6f  e SQLITE_TEXT co
2ef00 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f 20  nstant was also 
2ef10 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20 76  used in SQLite v
2ef20 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20  ersion 2.** for 
2ef30 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69 66  a completely dif
2ef40 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e 20  ferent meaning. 
2ef50 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20 6c   Software that l
2ef60 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f 74  inks against bot
2ef70 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  h.** SQLite vers
2ef80 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74 65  ion 2 and SQLite
2ef90 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75 6c   version 3 shoul
2efa0 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54 45  d use SQLITE3_TE
2efb0 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54  XT, not.** SQLIT
2efc0 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66 69  E_TEXT..*/.#defi
2efd0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  ne SQLITE_INTEGE
2efe0 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c  R  1.#define SQL
2eff0 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a 23  ITE_FLOAT    2.#
2f000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 4c  define SQLITE_BL
2f010 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65  OB     4.#define
2f020 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20 20   SQLITE_NULL    
2f030 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45   5.#ifdef SQLITE
2f040 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53 51  _TEXT.# undef SQ
2f050 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65 0a  LITE_TEXT.#else.
2f060 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2f070 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64 69  TEXT     3.#endi
2f080 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  f.#define SQLITE
2f090 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f 2a  3_TEXT     3../*
2f0a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2f0b0 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f 6d  sult Values From
2f0c0 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59 57   A Query.** KEYW
2f0d0 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63  ORDS: {column ac
2f0e0 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d 0a  cess functions}.
2f0f0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
2f100 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22 72  ines form the "r
2f110 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65 72  esult set" inter
2f120 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  face..**.** ^The
2f130 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  se routines retu
2f140 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2f150 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63 6f  bout a single co
2f160 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72 72  lumn of the curr
2f170 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f  ent.** result ro
2f180 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20 5e  w of a query.  ^
2f190 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74 68  In every case th
2f1a0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2f1b0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   is a pointer.**
2f1c0 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72 65   to the [prepare
2f1d0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2f1e0 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c 75  t is being evalu
2f1f0 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  ated (the [sqlit
2f200 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61  e3_stmt*].** tha
2f210 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20 66  t was returned f
2f220 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  rom [sqlite3_pre
2f230 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f 6e  pare_v2()] or on
2f240 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e 74  e of its variant
2f250 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73 65  s).** and the se
2f260 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
2f270 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
2f280 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68 69  e column for whi
2f290 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a  ch information.*
2f2a0 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  * should be retu
2f2b0 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74 6d  rned. ^The leftm
2f2c0 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  ost column of th
2f2d0 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61 73  e result set has
2f2e0 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a 2a   the index 0..**
2f2f0 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66 20   ^The number of 
2f300 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
2f310 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65 74  esult can be det
2f320 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  ermined using.**
2f330 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2f340 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _count()]..**.**
2f350 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74   If the SQL stat
2f360 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
2f370 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20 74  urrently point t
2f380 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20 6f  o a valid row, o
2f390 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c 75  r if the.** colu
2f3a0 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  mn index is out 
2f3b0 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72 65  of range, the re
2f3c0 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65  sult is undefine
2f3d0 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  d..** These rout
2f3e0 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ines may only be
2f3f0 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
2f400 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c   most recent cal
2f410 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
2f420 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65 74  _step()] has ret
2f430 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f  urned [SQLITE_RO
2f440 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a 2a  W] and neither.*
2f450 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
2f460 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65 33  ()] nor [sqlite3
2f470 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61 76  _finalize()] hav
2f480 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73 75  e been called su
2f490 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49  bsequently..** I
2f4a0 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  f any of these r
2f4b0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
2f4c0 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  ed after [sqlite
2f4d0 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a  3_reset()] or.**
2f4e0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2f4f0 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 5b  ze()] or after [
2f500 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2f510 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  has returned.** 
2f520 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
2f530 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2f540 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ], the results a
2f550 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
2f560 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   If [sqlite3_ste
2f570 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2f580 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2f590 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f5a0 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64 20  ].** are called 
2f5b0 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e 74  from a different
2f5c0 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61 6e   thread while an
2f5d0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2f5e0 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64 69  nes.** are pendi
2f5f0 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73  ng, then the res
2f600 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2f610 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
2f620 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2f630 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  pe() routine ret
2f640 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  urns the.** [SQL
2f650 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61  ITE_INTEGER | da
2f660 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f 72  tatype code] for
2f670 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61 74   the initial dat
2f680 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68 65  a type.** of the
2f690 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20   result column. 
2f6a0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 76   ^The returned v
2f6b0 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20 5b  alue is one of [
2f6c0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d 2c  SQLITE_INTEGER],
2f6d0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f 41  .** [SQLITE_FLOA
2f6e0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58 54  T], [SQLITE_TEXT
2f6f0 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42 5d  ], [SQLITE_BLOB]
2f700 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55 4c  , or [SQLITE_NUL
2f710 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a 2a  L].  The value.*
2f720 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  * returned by sq
2f730 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
2f740 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61 6e  e() is only mean
2f750 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79 70  ingful if no typ
2f760 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 73  e.** conversions
2f770 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20 61   have occurred a
2f780 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c 6f  s described belo
2f790 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70 65  w.  After a type
2f7a0 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20   conversion,.** 
2f7b0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
2f7c0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2f7d0 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 75  lumn_type() is u
2f7e0 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75 72  ndefined.  Futur
2f7f0 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f 66  e.** versions of
2f800 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61 6e   SQLite may chan
2f810 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  ge the behavior 
2f820 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  of sqlite3_colum
2f830 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c  n_type().** foll
2f840 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f 6e  owing a type con
2f850 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  version..**.** ^
2f860 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2f870 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 38   a BLOB or UTF-8
2f880 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
2f890 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f8a0 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74 69  bytes().** routi
2f8b0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ne returns the n
2f8c0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
2f8d0 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20 73  n that BLOB or s
2f8e0 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2f8f0 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55 54  e result is a UT
2f900 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68 65  F-16 string, the
2f910 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2f920 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72 74  _bytes() convert
2f930 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  s.** the string 
2f940 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68 65  to UTF-8 and the
2f950 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
2f960 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a  mber of bytes..*
2f970 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2f980 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61   is a numeric va
2f990 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  lue then sqlite3
2f9a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2f9b0 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  uses.** [sqlite3
2f9c0 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20  _snprintf()] to 
2f9d0 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c  convert that val
2f9e0 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73 74  ue to a UTF-8 st
2f9f0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
2fa00 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
2fa10 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2fa20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2fa30 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
2fa40 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
2fa50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 72  column_bytes() r
2fa60 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2fa70 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2fa80 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2fa90 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68 65  TF-16 string the
2faa0 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  n the sqlite3_co
2fab0 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a 2a  lumn_bytes16().*
2fac0 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  * routine return
2fad0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
2fae0 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c  bytes in that BL
2faf0 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a  OB or string..**
2fb00 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2fb10 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
2fb20 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2fb30 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2fb40 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65   converts.** the
2fb50 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 31   string to UTF-1
2fb60 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75 72  6 and then retur
2fb70 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2fb80 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74   bytes..** ^If t
2fb90 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 6e  he result is a n
2fba0 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68 65  umeric value the
2fbb0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
2fbc0 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73 0a  _bytes16() uses.
2fbd0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
2fbe0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
2fbf0 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
2fc00 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67   a UTF-16 string
2fc10 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2fc20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2fc30 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2fc40 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2fc50 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2fc60 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2fc70 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65 74  mn_bytes16() ret
2fc80 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a  urns zero..**.**
2fc90 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
2fca0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2fcb0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2fcc0 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  ] and .** [sqlit
2fcd0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2fce0 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63 6c  6()] do not incl
2fcf0 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65 72  ude the zero ter
2fd00 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65 20  minators at the 
2fd10 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73 74  end.** of the st
2fd20 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61 72  ring.  ^For clar
2fd30 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73 20  ity: the values 
2fd40 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2fd50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fd60 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71 6c  ytes()] and [sql
2fd70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2fd80 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20 6e  s16()] are the n
2fd90 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74 65  umber of.** byte
2fda0 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 2c  s in the string,
2fdb0 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20   not the number 
2fdc0 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  of characters..*
2fdd0 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72 65  *.** ^Strings re
2fde0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2fdf0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
2fe00 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2fe10 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a 20  mn_text16(),.** 
2fe20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  even empty strin
2fe30 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20 7a  gs, are always z
2fe40 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
2fe50 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a 20   ^The return.** 
2fe60 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74  value from sqlit
2fe70 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2fe80 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e 67   for a zero-leng
2fe90 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55 4c  th BLOB is a NUL
2fea0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
2feb0 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65 74   ^The object ret
2fec0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
2fed0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
2fee0 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72  ] is an.** [unpr
2fef0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2ff00 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20 20  value] object.  
2ff10 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73  An unprotected s
2ff20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2ff30 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20  ect.** may only 
2ff40 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73 71  be used with [sq
2ff50 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65  lite3_bind_value
2ff60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2ff70 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2ff80 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e 70  ..** If the [unp
2ff90 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ffa0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 72  _value] object r
2ffb0 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73  eturned by.** [s
2ffc0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2ffd0 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20 69  lue()] is used i
2ffe0 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79 2c  n any other way,
2fff0 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c 73   including calls
30000 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73 20  .** to routines 
30010 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76 61  like [sqlite3_va
30020 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71 6c  lue_int()], [sql
30030 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
30040 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
30050 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29  e3_value_bytes()
30060 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ], then the beha
30070 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
30080 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  d..**.** These r
30090 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74 20  outines attempt 
300a0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
300b0 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72 6f  alue where appro
300c0 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a  priate.  ^For.**
300d0 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68 65   example, if the
300e0 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73   internal repres
300f0 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f 41  entation is FLOA
30100 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65 73  T and a text res
30110 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65 73  ult.** is reques
30120 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6e  ted, [sqlite3_sn
30130 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73 65  printf()] is use
30140 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
30150 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20 63  perform the.** c
30160 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d 61  onversion automa
30170 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65 20  tically.  ^(The 
30180 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65 20  following table 
30190 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e 76  details the conv
301a0 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74 20  ersions.** that 
301b0 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a  are applied:.**.
301c0 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  ** <blockquote>.
301d0 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72  ** <table border
301e0 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ="1">.** <tr><th
301f0 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54 79  > Internal<br>Ty
30200 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74 65  pe <th> Requeste
30210 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  d<br>Type <th>  
30220 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a  Conversion.**.**
30230 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
30240 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
30250 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
30260 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20   0.** <tr><td>  
30270 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46 4c  NULL    <td>  FL
30280 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73 75  OAT    <td> Resu
30290 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74 72  lt is 0.0.** <tr
302a0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
302b0 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
302c0 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
302d0 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
302e0 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
302f0 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
30300 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e 55 4c  d> Result is NUL
30310 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c 74 72  L pointer.** <tr
30320 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c  ><td> INTEGER  <
30330 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
30340 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
30350 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f 61 74  integer to float
30360 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
30370 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54 45 58  EGER  <td>   TEX
30380 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
30390 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
303a0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
303b0 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74  <td> INTEGER  <t
303c0 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
303d0 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45 47 45  > Same as INTEGE
303e0 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c  R->TEXT.** <tr><
303f0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
30400 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
30410 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20 66 6c   Convert from fl
30420 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72 0a 2a  oat to integer.*
30430 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
30440 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20  T   <td>   TEXT 
30450 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65     <td> ASCII re
30460 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66  ndering of the f
30470 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
30480 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20    FLOAT   <td>  
30490 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
304a0 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54 45 58  me as FLOAT->TEX
304b0 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  T.** <tr><td>  T
304c0 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  EXT    <td> INTE
304d0 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65 20 61  GER   <td> Use a
304e0 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
304f0 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
30500 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 55   FLOAT    <td> U
30510 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
30520 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
30530 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74  td>   BLOB    <t
30540 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  d> No change.** 
30550 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20  <tr><td>  BLOB  
30560 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
30570 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f   <td> Convert to
30580 20 54 45 58 54 20 74 68 65 6e 20 75 73 65 20 61   TEXT then use a
30590 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  toi().** <tr><td
305a0 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20  >  BLOB    <td> 
305b0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
305c0 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20 74  onvert to TEXT t
305d0 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29 0a 2a  hen use atof().*
305e0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
305f0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
30600 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
30610 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
30620 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
30630 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
30640 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
30650 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
30660 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
30670 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
30680 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
30690 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
306a0 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
306b0 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
306c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
306d0 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
306e0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
306f0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
30700 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
30710 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
30720 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
30730 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
30740 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
30750 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
30760 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
30770 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
30780 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
30790 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
307a0 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
307b0 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
307c0 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
307d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
307e0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
307f0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
30800 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
30810 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
30820 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
30830 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
30840 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
30850 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
30860 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
30870 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
30880 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
30890 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
308a0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
308b0 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
308c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
308d0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
308e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
308f0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
30900 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
30910 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
30920 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
30930 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
30940 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
30950 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
30960 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
30970 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
30980 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
30990 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
309a0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
309b0 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
309c0 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
309d0 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
309e0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
309f0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
30a00 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
30a10 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
30a20 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
30a30 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
30a40 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
30a50 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
30a60 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
30a70 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
30a80 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
30a90 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
30aa0 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
30ab0 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
30ac0 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
30ad0 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
30ae0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
30af0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
30b00 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
30b10 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
30b20 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
30b30 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
30b40 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
30b50 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
30b60 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
30b70 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
30b80 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
30b90 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
30ba0 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
30bb0 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
30bc0 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
30bd0 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
30be0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
30bf0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
30c00 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
30c10 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
30c20 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
30c30 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
30c40 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
30c50 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
30c60 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
30c70 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
30c80 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
30c90 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
30ca0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30cb0 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
30cc0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
30cd0 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
30ce0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
30cf0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
30d00 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
30d10 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
30d20 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
30d30 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
30d40 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
30d50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30d60 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
30d70 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
30d80 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
30d90 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
30da0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30db0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
30dc0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
30dd0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30de0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
30df0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
30e00 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
30e10 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
30e20 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
30e30 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
30e40 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
30e50 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
30e60 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
30e70 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
30e80 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
30e90 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
30ea0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
30eb0 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
30ec0 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
30ed0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
30ee0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
30ef0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
30f00 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
30f10 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30f20 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
30f30 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
30f40 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
30f50 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
30f60 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
30f70 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
30f80 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
30f90 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
30fa0 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
30fb0 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
30fc0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
30fd0 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
30fe0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
30ff0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
31000 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
31010 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
31020 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
31030 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
31040 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
31050 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
31060 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
31070 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  rned.** [sqlite3
31080 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c  _column_blob()],
31090 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
310a0 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e 20 69  _text()], etc. i
310b0 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  nto.** [sqlite3_
310c0 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  free()]..**.** ^
310d0 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  (If a memory all
310e0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63  ocation error oc
310f0 63 75 72 73 20 64 75 72 69 6e 67 20 74 68 65 20  curs during the 
31100 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 61 6e  evaluation of an
31110 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20 72 6f  y.** of these ro
31120 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61 75 6c  utines, a defaul
31130 74 20 76 61 6c 75 65 20 69 73 20 72 65 74 75 72  t value is retur
31140 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61 75 6c  ned.  The defaul
31150 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20 65 69  t value.** is ei
31160 74 68 65 72 20 74 68 65 20 69 6e 74 65 67 65 72  ther the integer
31170 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69 6e 67   0, the floating
31180 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20 30 2e   point number 0.
31190 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20  0, or a NULL.** 
311a0 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73 65 71  pointer.  Subseq
311b0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
311c0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
311d0 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a  ] will return.**
311e0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
311f0 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
31200 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
31210 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
31220 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31230 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
31240 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
31250 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73  3_column_bytes(s
31260 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
31270 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
31280 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
31290 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 73  column_bytes16(s
312a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
312b0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
312c0 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  API double sqlit
312d0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
312e0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
312f0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
31300 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
31310 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
31320 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31330 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
31340 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
31350 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
31360 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
31370 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
31380 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
31390 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
313a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
313b0 78 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  xt(sqlite3_stmt*
313c0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
313d0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
313e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
313f0 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  mn_text16(sqlite
31400 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
31410 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  l);.SQLITE_API i
31420 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
31430 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  n_type(sqlite3_s
31440 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31450 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
31460 74 65 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74  te3_value *sqlit
31470 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
31480 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
31490 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  nt iCol);../*.**
314a0 20 43 41 50 49 33 52 45 46 3a 20 44 65 73 74 72   CAPI3REF: Destr
314b0 6f 79 20 41 20 50 72 65 70 61 72 65 64 20 53 74  oy A Prepared St
314c0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
314d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
314e0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e  3_finalize() fun
314f0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
31500 74 6f 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65  to delete a [pre
31510 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
31520 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73  ..** ^If the mos
31530 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74  t recent evaluat
31540 69 6f 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65  ion of the state
31550 6d 65 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64  ment encountered
31560 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 72   no errors.** or
31570 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
31580 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
31590 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
315a0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
315b0 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
315c0 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
315d0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
315e0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
315f0 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
31600 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
31610 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
31620 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
31630 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
31640 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
31650 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
31660 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
31670 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
31680 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
31690 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
316a0 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
316b0 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
316c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
316d0 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
316e0 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
316f0 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
31700 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
31710 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
31720 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
31730 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
31740 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
31750 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
31760 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
31770 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
31780 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
31790 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
317a0 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
317b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
317c0 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
317d0 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
317e0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
317f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
31800 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
31810 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
31820 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
31830 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
31840 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
31850 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
31860 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
31870 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
31880 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
31890 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
318a0 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
318b0 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
318c0 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
318d0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
318e0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
318f0 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
31900 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
31910 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
31920 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
31930 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
31940 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
31950 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
31960 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
31970 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33  finalize(sqlite3
31980 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
31990 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
319a0 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65 64  Reset A Prepared
319b0 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63   Statement Objec
319c0 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  t.**.** The sqli
319d0 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63  te3_reset() func
319e0 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74  tion is called t
319f0 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70 61  o reset a [prepa
31a00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a  red statement].*
31a10 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f  * object back to
31a20 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61   its initial sta
31a30 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20  te, ready to be 
31a40 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20  re-executed..** 
31a50 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65  ^Any SQL stateme
31a60 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68 61  nt variables tha
31a70 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75  t had values bou
31a80 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67  nd to them using
31a90 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
31aa0 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c  _bind_blob | sql
31ab0 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50  ite3_bind_*() AP
31ac0 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72 20  I] retain their 
31ad0 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b  values..** Use [
31ae0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
31af0 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73  ndings()] to res
31b00 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e  et the bindings.
31b10 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  .**.** ^The [sql
31b20 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69  ite3_reset(S)] i
31b30 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73 20  nterface resets 
31b40 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
31b50 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61  atement] S.** ba
31b60 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ck to the beginn
31b70 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72  ing of its progr
31b80 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  am..**.** ^If th
31b90 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
31ba0 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
31bb0 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
31bc0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
31bd0 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e  tement] S return
31be0 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  ed [SQLITE_ROW] 
31bf0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
31c00 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69  ,.** or if [sqli
31c10 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73  te3_step(S)] has
31c20 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62 65   never before be
31c30 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a  en called on S,.
31c40 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33  ** then [sqlite3
31c50 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
31c60 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a  ns [SQLITE_OK]..
31c70 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
31c80 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
31c90 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
31ca0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
31cb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
31cc0 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20  nt] S indicated 
31cd0 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a  an error, then.*
31ce0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  * [sqlite3_reset
31cf0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20  (S)] returns an 
31d00 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72  appropriate [err
31d10 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
31d20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
31d30 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
31d40 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67  e does not chang
31d50 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20  e the values.** 
31d60 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f  of any [sqlite3_
31d70 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e  bind_blob|bindin
31d80 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70  gs] on the [prep
31d90 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31da0 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  S..*/.SQLITE_API
31db0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73   int sqlite3_res
31dc0 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  et(sqlite3_stmt 
31dd0 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
31de0 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74 65  CAPI3REF: Create
31df0 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c   Or Redefine SQL
31e00 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45   Functions.** KE
31e10 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f  YWORDS: {functio
31e20 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
31e30 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  nes}.** KEYWORDS
31e40 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
31e50 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
31e60 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ion}.** KEYWORDS
31e70 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  : {application-d
31e80 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
31e90 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ions}.**.** ^The
31ea0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f  se functions (co
31eb0 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e  llectively known
31ec0 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72   as "function cr
31ed0 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22  eation routines"
31ee0 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f  ).** are used to
31ef0 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f   add SQL functio
31f00 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65 73  ns or aggregates
31f10 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20   or to redefine 
31f20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20  the behavior.** 
31f30 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20  of existing SQL 
31f40 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67  functions or agg
31f50 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e  regates.  The on
31f60 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20 62  ly differences b
31f70 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20  etween.** these 
31f80 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68 65  routines are the
31f90 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65   text encoding e
31fa0 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74  xpected for.** t
31fb0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
31fc0 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66  ter (the name of
31fd0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65   the function be
31fe0 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20  ing created).** 
31ff0 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63 65  and the presence
32000 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61   or absence of a
32010 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
32020 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20  back for.** the 
32030 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
32040 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
32050 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  ^The first param
32060 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61 74  eter is the [dat
32070 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32080 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20 53  ] to which the S
32090 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  QL.** function i
320a0 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20  s to be added.  
320b0 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69  ^If an applicati
320c0 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61  on uses more tha
320d0 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a  n one database.*
320e0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65  * connection the
320f0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
32100 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
32110 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64 65  ons must be adde
32120 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74  d.** to each dat
32130 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32140 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a   separately..**.
32150 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  ** ^The second p
32160 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
32170 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20  name of the SQL 
32180 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63  function to be c
32190 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64  reated or.** red
321a0 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65  efined.  ^The le
321b0 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65  ngth of the name
321c0 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32   is limited to 2
321d0 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55 54  55 bytes in a UT
321e0 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74  F-8.** represent
321f0 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65  ation, exclusive
32200 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   of the zero-ter
32210 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20  minator.  ^Note 
32220 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a  that the name.**
32230 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73   length limit is
32240 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c   in UTF-8 bytes,
32250 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 20   not characters 
32260 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65 73  nor UTF-16 bytes
32270 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65  .  .** ^Any atte
32280 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61 20  mpt to create a 
32290 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
322a0 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77  longer name.** w
322b0 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53  ill result in [S
322c0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65  QLITE_MISUSE] be
322d0 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a  ing returned..**
322e0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70  .** ^The third p
322f0 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a  arameter (nArg).
32300 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  ** is the number
32310 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68   of arguments th
32320 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  at the SQL funct
32330 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67  ion or.** aggreg
32340 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74  ate takes. ^If t
32350 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69 73  his parameter is
32360 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51   -1, then the SQ
32370 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
32380 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20 74   aggregate may t
32390 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f  ake any number o
323a0 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77  f arguments betw
323b0 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69  een 0 and the li
323c0 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73  mit.** set by [s
323d0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53  qlite3_limit]([S
323e0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
323f0 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20  TION_ARG]).  If 
32400 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72  the third.** par
32410 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20 74  ameter is less t
32420 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65  han -1 or greate
32430 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20  r than 127 then 
32440 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a  the behavior is.
32450 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
32460 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
32470 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74  parameter, eText
32480 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20 77  Rep, specifies w
32490 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55  hat.** [SQLITE_U
324a0 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64  TF8 | text encod
324b0 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75  ing] this SQL fu
324c0 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66  nction prefers f
324d0 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65  or.** its parame
324e0 74 65 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c  ters.  Every SQL
324f0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
32500 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65  entation must be
32510 20 61 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a   able to work.**
32520 20 77 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46   with UTF-8, UTF
32530 2d 31 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36  -16le, or UTF-16
32540 62 65 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d  be.  But some im
32550 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61  plementations ma
32560 79 20 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66  y be.** more eff
32570 69 63 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20  icient with one 
32580 65 6e 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e  encoding than an
32590 6f 74 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c  other.  ^An appl
325a0 69 63 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69  ication may.** i
325b0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72  nvoke sqlite3_cr
325c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20  eate_function() 
325d0 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
325e0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d  e_function16() m
325f0 75 6c 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73  ultiple.** times
32600 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 66   with the same f
32610 75 6e 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68  unction but with
32620 20 64 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65   different value
32630 73 20 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a  s of eTextRep..*
32640 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
32650 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
32660 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
32670 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
32680 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
32690 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
326a0 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
326b0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
326c0 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
326d0 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20  on..** If there 
326e0 69 73 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65  is only a single
326f0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
32700 77 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63  which does not c
32710 61 72 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a  are what text.**
32720 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65   encoding is use
32730 64 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72  d, then the four
32740 74 68 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  th argument shou
32750 6c 64 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e  ld be [SQLITE_AN
32760 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  Y]..**.** ^(The 
32770 66 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20  fifth parameter 
32780 69 73 20 61 6e 20 61 72 62 69 74 72 61 72 79 20  is an arbitrary 
32790 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d  pointer.  The im
327a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
327b0 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
327c0 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20  can gain access 
327d0 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20  to this pointer 
327e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75  using [sqlite3_u
327f0 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a  ser_data()].)^.*
32800 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c  *.** ^The sixth,
32810 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67   seventh and eig
32820 68 74 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20  hth parameters, 
32830 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64  xFunc, xStep and
32840 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20   xFinal, are.** 
32850 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61  pointers to C-la
32860 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73  nguage functions
32870 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20   that implement 
32880 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
32890 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
328a0 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20  . ^A scalar SQL 
328b0 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
328c0 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
328d0 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63  ion of the xFunc
328e0 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c  .** callback onl
328f0 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  y; NULL pointers
32900 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
32910 61 73 20 74 68 65 20 78 53 74 65 70 20 61 6e 64  as the xStep and
32920 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d   xFinal.** param
32930 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65  eters. ^An aggre
32940 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
32950 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d  n requires an im
32960 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
32970 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69  xStep.** and xFi
32980 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69  nal and NULL poi
32990 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70 61 73  nter must be pas
329a0 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e  sed for xFunc. ^
329b0 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69  To delete an exi
329c0 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e  sting.** SQL fun
329d0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
329e0 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f  te, pass NULL po
329f0 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74  inters for all t
32a00 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  hree function.**
32a10 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a   callbacks..**.*
32a20 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68  * ^(If the ninth
32a30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
32a40 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
32a50 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f  ction_v2() is no
32a60 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20  t NULL,.** then 
32a70 69 74 20 69 73 20 64 65 73 74 72 75 63 74 6f 72  it is destructor
32a80 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61   for the applica
32a90 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
32aa0 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72  r. .** The destr
32ab0 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64  uctor is invoked
32ac0 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69   when the functi
32ad0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65  on is deleted, e
32ae0 69 74 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a  ither by being.*
32af0 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20  * overloaded or 
32b00 77 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  when the databas
32b10 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f  e connection clo
32b20 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64  ses.)^.** ^The d
32b30 65 73 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73  estructor is als
32b40 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65  o invoked if the
32b50 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
32b60 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
32b70 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a  ion_v2() fails..
32b80 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73  ** ^When the des
32b90 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
32ba0 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20 70 61   of the tenth pa
32bb0 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b  rameter is invok
32bc0 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73  ed, it.** is pas
32bd0 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67  sed a single arg
32be0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
32bf0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70   copy of the app
32c00 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a  lication data .*
32c10 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20  * pointer which 
32c20 77 61 73 20 74 68 65 20 66 69 66 74 68 20 70 61  was the fifth pa
32c30 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
32c40 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
32c50 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  on_v2()..**.** ^
32c60 49 74 20 69 73 20 70 65 72 6d 69 74 74 65 64 20  It is permitted 
32c70 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74  to register mult
32c80 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
32c90 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
32ca0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69  .** functions wi
32cb0 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65  th the same name
32cc0 20 62 75 74 20 77 69 74 68 20 65 69 74 68 65 72   but with either
32cd0 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65   differing numbe
32ce0 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e  rs of.** argumen
32cf0 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20  ts or differing 
32d00 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
32d10 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69  ncodings.  ^SQLi
32d20 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74  te will use.** t
32d30 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
32d40 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73  n that most clos
32d50 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68 65 20  ely matches the 
32d60 77 61 79 20 69 6e 20 77 68 69 63 68 20 74 68 65  way in which the
32d70 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
32d80 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75   is used.  ^A fu
32d90 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
32da0 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e  ation with a non
32db0 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72  -negative.** nAr
32dc0 67 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  g parameter is a
32dd0 20 62 65 74 74 65 72 20 6d 61 74 63 68 20 74 68   better match th
32de0 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d  an a function im
32df0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
32e00 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20  h.** a negative 
32e10 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69  nArg.  ^A functi
32e20 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70 72 65  on where the pre
32e30 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f  ferred text enco
32e40 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20  ding.** matches 
32e50 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 63  the database enc
32e60 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74 74 65  oding is a bette
32e70 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20  r.** match than 
32e80 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
32e90 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73   the encoding is
32ea0 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a   different.  .**
32eb0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
32ec0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
32ed0 64 69 66 66 65 72 65 6e 63 65 20 69 73 20 62 65  difference is be
32ee0 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e  tween UTF16le an
32ef0 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20  d UTF16be.** is 
32f00 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74  a closer match t
32f10 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
32f20 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
32f30 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a  g difference is.
32f40 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46 38 20  ** between UTF8 
32f50 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a  and UTF16..**.**
32f60 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74   ^Built-in funct
32f70 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72  ions may be over
32f80 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20 61 70  loaded by new ap
32f90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
32fa0 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  d functions..**.
32fb0 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  ** ^An applicati
32fc0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
32fd0 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
32fe0 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a   to call other.*
32ff0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  * SQLite interfa
33000 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73  ces.  However, s
33010 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e  uch calls must n
33020 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20  ot.** close the 
33030 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33040 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65  ion nor finalize
33050 20 6f 72 20 72 65 73 65 74 20 74 68 65 20 70 72   or reset the pr
33060 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d  epared.** statem
33070 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74 68 65  ent in which the
33080 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
33090 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ning..*/.SQLITE_
330a0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
330b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
330c0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
330d0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
330e0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
330f0 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
33100 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
33110 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
33120 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
33130 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
33140 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
33150 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
33160 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
33170 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
33180 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
33190 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
331a0 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54  ntext*).);.SQLIT
331b0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
331c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
331d0 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  n16(.  sqlite3 *
331e0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  db,.  const void
331f0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
33200 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
33210 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
33220 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
33230 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
33240 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33250 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33260 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
33270 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
33280 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
33290 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
332a0 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
332b0 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53  3_context*).);.S
332c0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
332d0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
332e0 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69  ction_v2(.  sqli
332f0 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
33300 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
33310 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
33320 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
33330 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
33340 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
33350 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33360 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
33370 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
33380 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
33390 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
333a0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
333b0 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
333c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
333d0 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
333e0 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  oy)(void*).);../
333f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
33400 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a  ext Encodings.**
33410 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
33420 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67 65  nt define intege
33430 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65 70  r codes that rep
33440 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69 6f  resent the vario
33450 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64  us.** text encod
33460 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20 62  ings supported b
33470 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65  y SQLite..*/.#de
33480 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 38  fine SQLITE_UTF8
33490 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
334a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
334b0 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64 65  6LE        2.#de
334c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
334d0 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64 65  6BE        3.#de
334e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31  fine SQLITE_UTF1
334f0 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20 20  6          4    
33500 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62 79  /* Use native by
33510 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66  te order */.#def
33520 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20 20  ine SQLITE_ANY  
33530 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20 2f            5    /
33540 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
33550 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a  _function only *
33560 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
33570 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20  _UTF16_ALIGNED  
33580 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  8    /* sqlite3_
33590 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
335a0 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   only */../*.** 
335b0 43 41 50 49 33 52 45 46 3a 20 44 65 70 72 65 63  CAPI3REF: Deprec
335c0 61 74 65 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ated Functions.*
335d0 2a 20 44 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a  * DEPRECATED.**.
335e0 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f  ** These functio
335f0 6e 73 20 61 72 65 20 5b 64 65 70 72 65 63 61 74  ns are [deprecat
33600 65 64 5d 2e 20 20 49 6e 20 6f 72 64 65 72 20 74  ed].  In order t
33610 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61  o maintain.** ba
33620 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
33630 69 6c 69 74 79 20 77 69 74 68 20 6f 6c 64 65 72  ility with older
33640 20 63 6f 64 65 2c 20 74 68 65 73 65 20 66 75 6e   code, these fun
33650 63 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20  ctions continue 
33660 0a 2a 2a 20 74 6f 20 62 65 20 73 75 70 70 6f 72  .** to be suppor
33670 74 65 64 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e  ted.  However, n
33680 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ew applications 
33690 73 68 6f 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20  should avoid.** 
336a0 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 73 65  the use of these
336b0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20   functions.  To 
336c0 68 65 6c 70 20 65 6e 63 6f 75 72 61 67 65 20 70  help encourage p
336d0 65 6f 70 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a  eople to avoid.*
336e0 2a 20 75 73 69 6e 67 20 74 68 65 73 65 20 66 75  * using these fu
336f0 6e 63 74 69 6f 6e 73 2c 20 77 65 20 61 72 65 20  nctions, we are 
33700 6e 6f 74 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c  not going to tel
33710 6c 20 79 6f 75 20 77 68 61 74 20 74 68 65 79 20  l you what they 
33720 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  do..*/.#ifndef S
33730 51 4c 49 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45  QLITE_OMIT_DEPRE
33740 43 41 54 45 44 0a 53 51 4c 49 54 45 5f 41 50 49  CATED.SQLITE_API
33750 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
33760 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61  ED int sqlite3_a
33770 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73  ggregate_count(s
33780 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
33790 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  ;.SQLITE_API SQL
337a0 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
337b0 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69 72  nt sqlite3_expir
337c0 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ed(sqlite3_stmt*
337d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51  );.SQLITE_API SQ
337e0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
337f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 72 61 6e  int sqlite3_tran
33800 73 66 65 72 5f 62 69 6e 64 69 6e 67 73 28 73 71  sfer_bindings(sq
33810 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 73 71 6c  lite3_stmt*, sql
33820 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
33830 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
33840 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
33850 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
33860 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
33870 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
33880 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
33890 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
338a0 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
338b0 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
338c0 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
338d0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72  ite3_memory_alar
338e0 6d 28 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  m(void(*)(void*,
338f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2c 69 6e  sqlite3_int64,in
33900 74 29 2c 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  t),void*,sqlite3
33910 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a  _int64);.#endif.
33920 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
33930 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46   Obtaining SQL F
33940 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65  unction Paramete
33950 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54  r Values.**.** T
33960 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d  he C-language im
33970 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
33980 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e  SQL functions an
33990 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73 65  d aggregates use
339a0 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66  s.** this set of
339b0 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69   interface routi
339c0 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74 68  nes to access th
339d0 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75  e parameter valu
339e0 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e  es on.** the fun
339f0 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61  ction or aggrega
33a00 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46  te..**.** The xF
33a10 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20  unc (for scalar 
33a20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53  functions) or xS
33a30 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67 61  tep (for aggrega
33a40 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a  tes) parameters.
33a50 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ** to [sqlite3_c
33a60 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
33a70 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
33a80 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
33a90 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61  ()].** define ca
33aa0 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70  llbacks that imp
33ab0 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
33ac0 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
33ad0 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20  regates..** The 
33ae0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
33af0 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73   these callbacks
33b00 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
33b10 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b  pointers to.** [
33b20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
33b30 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
33b40 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20  .  There is one 
33b50 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
33b60 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61  object for.** ea
33b70 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ch parameter to 
33b80 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
33b90 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
33ba0 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a  s are used to.**
33bb0 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73 20   extract values 
33bc0 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65  from the [sqlite
33bd0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73  3_value] objects
33be0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
33bf0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79  utines work only
33c00 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64   with [protected
33c10 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
33c20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20  objects..** Any 
33c30 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
33c40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e  hese routines on
33c50 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64   an [unprotected
33c60 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a   sqlite3_value].
33c70 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74  ** object result
33c80 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62  s in undefined b
33c90 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e  ehavior..**.** ^
33ca0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
33cb0 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68  ork just like th
33cc0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
33cd0 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  [column access f
33ce0 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63  unctions].** exc
33cf0 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65 20  ept that  these 
33d00 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20  routines take a 
33d10 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65  single [protecte
33d20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
33d30 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74   object.** point
33d40 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  er instead of a 
33d50 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20  [sqlite3_stmt*] 
33d60 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69  pointer and an i
33d70 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75  nteger column nu
33d80 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  mber..**.** ^The
33d90 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
33da0 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61 63  ext16() interfac
33db0 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54 46  e extracts a UTF
33dc0 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e  -16 string.** in
33dd0 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
33de0 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f  -order of the ho
33df0 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68  st machine.  ^Th
33e00 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  e.** sqlite3_val
33e10 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e  ue_text16be() an
33e20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  d sqlite3_value_
33e30 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72  text16le() inter
33e40 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74  faces.** extract
33e50 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20   UTF-16 strings 
33e60 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e  as big-endian an
33e70 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20  d little-endian 
33e80 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
33e90 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
33ea0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
33eb0 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63 65  type() interface
33ec0 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70   attempts to app
33ed0 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66  ly.** numeric af
33ee0 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61  finity to the va
33ef0 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  lue.  This means
33f00 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74   that an attempt
33f10 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63   is.** made to c
33f20 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
33f30 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f   to an integer o
33f40 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  r floating point
33f50 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20  .  If.** such a 
33f60 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f  conversion is po
33f70 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c  ssible without l
33f80 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69  oss of informati
33f90 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20  on (in other.** 
33fa0 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76 61  words, if the va
33fb0 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67 20  lue is a string 
33fc0 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20  that looks like 
33fd0 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65  a number).** the
33fe0 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  n the conversion
33ff0 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20   is performed.  
34000 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e  Otherwise no con
34010 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a  version occurs..
34020 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  ** The [SQLITE_I
34030 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
34040 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73  e] after convers
34050 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ion is returned.
34060 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20  )^.**.** Please 
34070 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20 61  pay particular a
34080 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20  ttention to the 
34090 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70 6f  fact that the po
340a0 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a  inter returned.*
340b0 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
340c0 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b  value_blob()], [
340d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
340e0 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71  xt()], or.** [sq
340f0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34100 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76  16()] can be inv
34110 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73 75  alidated by a su
34120 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
34130 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
34140 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71  ue_bytes()], [sq
34150 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
34160 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  s16()], [sqlite3
34170 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
34180 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
34190 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a  alue_text16()]..
341a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
341b0 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c  ines must be cal
341c0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
341d0 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74  e thread as.** t
341e0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
341f0 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74 68  that supplied th
34200 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
34210 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a  *] parameters..*
34220 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
34230 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
34240 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
34250 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
34260 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
34270 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
34280 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34290 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
342a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
342b0 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
342c0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
342d0 49 20 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  I double sqlite3
342e0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
342f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
34300 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
34310 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
34320 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34330 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
34340 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
34350 33 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71  3_value_int64(sq
34360 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
34370 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
34380 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73  unsigned char *s
34390 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
343a0 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t(sqlite3_value*
343b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
343c0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
343d0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
343e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
343f0 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
34400 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76   void *sqlite3_v
34410 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71  alue_text16le(sq
34420 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
34430 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
34440 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
34450 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
34460 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51  ite3_value*);.SQ
34470 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
34480 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
34490 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
344a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
344b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75  sqlite3_value_nu
344c0 6d 65 72 69 63 5f 74 79 70 65 28 73 71 6c 69 74  meric_type(sqlit
344d0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a  e3_value*);../*.
344e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
344f0 61 69 6e 20 41 67 67 72 65 67 61 74 65 20 46 75  ain Aggregate Fu
34500 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a  nction Context.*
34510 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74  *.** Implementat
34520 69 6f 6e 73 20 6f 66 20 61 67 67 72 65 67 61 74  ions of aggregat
34530 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
34540 75 73 65 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74  use this.** rout
34550 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ine to allocate 
34560 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74 6f 72 69  memory for stori
34570 6e 67 20 74 68 65 69 72 20 73 74 61 74 65 2e 0a  ng their state..
34580 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
34590 20 74 69 6d 65 20 74 68 65 20 73 71 6c 69 74 65   time the sqlite
345a0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
345b0 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65  ext(C,N) routine
345c0 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66   is called .** f
345d0 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
345e0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
345f0 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c  on, SQLite.** al
34600 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d  locates N of mem
34610 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20  ory, zeroes out 
34620 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64  that memory, and
34630 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
34640 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77  er.** to the new
34650 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63   memory. ^On sec
34660 6f 6e 64 20 61 6e 64 20 73 75 62 73 65 71 75 65  ond and subseque
34670 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73  nt calls to.** s
34680 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
34690 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f 72 20 74  _context() for t
346a0 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61 74  he same aggregat
346b0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61  e function insta
346c0 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65  nce,.** the same
346d0 20 62 75 66 66 65 72 20 69 73 20 72 65 74 75 72   buffer is retur
346e0 6e 65 64 2e 20 20 53 71 6c 69 74 65 33 5f 61 67  ned.  Sqlite3_ag
346f0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
34700 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a  ) is normally.**
34710 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72   called once for
34720 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e   each invocation
34730 20 6f 66 20 74 68 65 20 78 53 74 65 70 20 63 61   of the xStep ca
34740 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68 65 6e 20  llback and then 
34750 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65  one.** last time
34760 20 77 68 65 6e 20 74 68 65 20 78 46 69 6e 61 6c   when the xFinal
34770 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
34780 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f  oked.  ^(When no
34790 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61   rows match.** a
347a0 6e 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72  n aggregate quer
347b0 79 2c 20 74 68 65 20 78 53 74 65 70 28 29 20 63  y, the xStep() c
347c0 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 61  allback of the a
347d0 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
347e0 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
347f0 69 6f 6e 20 69 73 20 6e 65 76 65 72 20 63 61 6c  ion is never cal
34800 6c 65 64 20 61 6e 64 20 78 46 69 6e 61 6c 28 29  led and xFinal()
34810 20 69 73 20 63 61 6c 6c 65 64 20 65 78 61 63 74   is called exact
34820 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74  ly once..** In t
34830 68 6f 73 65 20 63 61 73 65 73 2c 20 73 71 6c 69  hose cases, sqli
34840 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
34850 6e 74 65 78 74 28 29 20 6d 69 67 68 74 20 62 65  ntext() might be
34860 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a   called for the.
34870 2a 2a 20 66 69 72 73 74 20 74 69 6d 65 20 66 72  ** first time fr
34880 6f 6d 20 77 69 74 68 69 6e 20 78 46 69 6e 61 6c  om within xFinal
34890 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ().)^.**.** ^The
348a0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
348b0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
348c0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
348d0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
348e0 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73 73 20 74  f N is.** less t
348f0 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
34900 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
34910 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  ory allocate err
34920 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
34930 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
34940 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
34950 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
34960 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
34970 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
34980 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
34990 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
349a0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
349b0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
349c0 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
349d0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
349e0 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
349f0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
34a00 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
34a10 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
34a20 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
34a30 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
34a40 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
34a50 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20  cation.)^.**.** 
34a60 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69  ^SQLite automati
34a70 63 61 6c 6c 79 20 66 72 65 65 73 20 74 68 65 20  cally frees the 
34a80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 64  memory allocated
34a90 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   by .** sqlite3_
34aa0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
34ab0 74 28 29 20 77 68 65 6e 20 74 68 65 20 61 67 67  t() when the agg
34ac0 72 65 67 61 74 65 20 71 75 65 72 79 20 63 6f 6e  regate query con
34ad0 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  cludes..**.** Th
34ae0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
34af0 72 20 6d 75 73 74 20 62 65 20 61 20 63 6f 70 79  r must be a copy
34b00 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
34b10 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c 20 53 51  te3_context | SQ
34b20 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f 6e 74 65  L function conte
34b30 78 74 5d 20 74 68 61 74 20 69 73 20 74 68 65 20  xt] that is the 
34b40 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 0a  first parameter.
34b50 2a 2a 20 74 6f 20 74 68 65 20 78 53 74 65 70 20  ** to the xStep 
34b60 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
34b70 63 6b 20 72 6f 75 74 69 6e 65 20 74 68 61 74 20  ck routine that 
34b80 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 61  implements the a
34b90 67 67 72 65 67 61 74 65 0a 2a 2a 20 66 75 6e 63  ggregate.** func
34ba0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  tion..**.** This
34bb0 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65   routine must be
34bc0 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
34bd0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
34be0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 67 67  which.** the agg
34bf0 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
34c00 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
34c10 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
34c20 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72  id *sqlite3_aggr
34c30 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71  egate_context(sq
34c40 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
34c50 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a  int nBytes);../*
34c60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73  .** CAPI3REF: Us
34c70 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63  er Data For Func
34c80 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
34c90 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61   sqlite3_user_da
34ca0 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ta() interface r
34cb0 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66  eturns a copy of
34cc0 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20  .** the pointer 
34cd0 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55 73  that was the pUs
34ce0 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65 72  erData parameter
34cf0 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d 65   (the 5th parame
34d00 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
34d10 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
34d20 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
34d30 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
34d40 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
34d50 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
34d60 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
34d70 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
34d80 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
34d90 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
34da0 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
34db0 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
34dc0 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
34dd0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
34de0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
34df0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ned function is 
34e00 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49  running..*/.SQLI
34e10 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c  TE_API void *sql
34e20 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73  ite3_user_data(s
34e30 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
34e40 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34e50 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  F: Database Conn
34e60 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74  ection For Funct
34e70 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ions.**.** ^The 
34e80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
34e90 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65  db_handle() inte
34ea0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
34eb0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70  copy of.** the p
34ec0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64  ointer to the [d
34ed0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
34ee0 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61 72  on] (the 1st par
34ef0 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68  ameter).** of th
34f00 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  e [sqlite3_creat
34f10 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a  e_function()].**
34f20 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72   and [sqlite3_cr
34f30 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
34f40 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  )] routines that
34f50 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72   originally.** r
34f60 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61 70  egistered the ap
34f70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
34f80 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53  d function..*/.S
34f90 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65  QLITE_API sqlite
34fa0 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  3 *sqlite3_conte
34fb0 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  xt_db_handle(sql
34fc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
34fd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34fe0 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69 6c 69   Function Auxili
34ff0 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54  ary Data.**.** T
35000 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f  he following two
35010 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62   functions may b
35020 65 20 75 73 65 64 20 62 79 20 73 63 61 6c 61 72  e used by scalar
35030 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 74   SQL functions t
35040 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 20 6d  o.** associate m
35050 65 74 61 64 61 74 61 20 77 69 74 68 20 61 72 67  etadata with arg
35060 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20 49 66  ument values. If
35070 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75 65 20   the same value 
35080 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20  is passed to.** 
35090 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63 61 74  multiple invocat
350a0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
350b0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 64 75   SQL function du
350c0 72 69 6e 67 20 71 75 65 72 79 20 65 78 65 63 75  ring query execu
350d0 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a 20 73  tion, under.** s
350e0 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
350f0 73 20 74 68 65 20 61 73 73 6f 63 69 61 74 65 64  s the associated
35100 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20 62 65   metadata may be
35110 20 70 72 65 73 65 72 76 65 64 2e 20 54 68 69 73   preserved. This
35120 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65 64 2c   may.** be used,
35130 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   for example, to
35140 20 61 64 64 20 61 20 72 65 67 75 6c 61 72 2d 65   add a regular-e
35150 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69  xpression matchi
35160 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66 75 6e  ng scalar.** fun
35170 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d 70 69  ction. The compi
35180 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  led version of t
35190 68 65 20 72 65 67 75 6c 61 72 20 65 78 70 72 65  he regular expre
351a0 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65 64 20  ssion is stored 
351b0 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61  as.** metadata a
351c0 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
351d0 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70 61 73  he SQL value pas
351e0 73 65 64 20 61 73 20 74 68 65 20 72 65 67 75 6c  sed as the regul
351f0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a 2a 2a  ar expression.**
35200 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65 20 63   pattern.  The c
35210 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20  ompiled regular 
35220 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62  expression can b
35230 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74  e reused on mult
35240 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  iple.** invocati
35250 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
35260 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68 61 74  function so that
35270 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 70 61   the original pa
35280 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a 2a 20  ttern string.** 
35290 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
352a0 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64 20 6f   be recompiled o
352b0 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74 69 6f  n each invocatio
352c0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  n..**.** ^The sq
352d0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
352e0 61 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  a() interface re
352f0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
35300 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a  to the metadata.
35310 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 62 79  ** associated by
35320 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74   the sqlite3_set
35330 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e 63 74  _auxdata() funct
35340 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e 74 68  ion with the Nth
35350 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c   argument.** val
35360 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63  ue to the applic
35370 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35380 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d  nction. ^If no m
35390 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65 6e  etadata has been
353a0 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20 73 65   ever.** been se
353b0 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20 61 72  t for the Nth ar
353c0 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20 66 75  gument of the fu
353d0 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20 74 68  nction, or if th
353e0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
353f0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61  ** function para
35400 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e 67 65  meter has change
35410 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65 74 61  d since the meta
35420 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c 0a 2a  -data was set,.*
35430 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 67  * then sqlite3_g
35440 65 74 5f 61 75 78 64 61 74 61 28 29 20 72 65 74  et_auxdata() ret
35450 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
35460 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
35470 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
35480 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
35490 73 61 76 65 73 20 74 68 65 20 6d 65 74 61 64 61  saves the metada
354a0 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f  ta.** pointed to
354b0 20 62 79 20 69 74 73 20 33 72 64 20 70 61 72 61   by its 3rd para
354c0 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d 65 74  meter as the met
354d0 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e 2d  adata for the N-
354e0 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6f  th.** argument o
354f0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
35500 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35510 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e 74 0a  on.  Subsequent.
35520 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ** calls to sqli
35530 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
35540 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e 20 74  ) might return t
35550 68 69 73 20 64 61 74 61 2c 20 69 66 20 69 74 20  his data, if it 
35560 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65 6e 20  has.** not been 
35570 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49  destroyed..** ^I
35580 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  f it is not NULL
35590 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 69 6e  , SQLite will in
355a0 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72 75 63  voke the destruc
355b0 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  tor.** function 
355c0 67 69 76 65 6e 20 62 79 20 74 68 65 20 34 74 68  given by the 4th
355d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
355e0 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
355f0 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65  a() on.** the me
35600 74 61 64 61 74 61 20 77 68 65 6e 20 74 68 65 20  tadata when the 
35610 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
35620 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
35630 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72 20 77   changes.** or w
35640 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  hen the SQL stat
35650 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65 73 2c  ement completes,
35660 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73   whichever comes
35670 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51   first..**.** SQ
35680 4c 69 74 65 20 69 73 20 66 72 65 65 20 74 6f 20  Lite is free to 
35690 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72 75 63  call the destruc
356a0 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d 65 74  tor and drop met
356b0 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20  adata on any.** 
356c0 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61 6e 79  parameter of any
356d0 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61 6e 79   function at any
356e0 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f 6e 6c   time.  ^The onl
356f0 79 20 67 75 61 72 61 6e 74 65 65 20 69 73 20 74  y guarantee is t
35700 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73 74 72  hat.** the destr
35710 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20 63 61  uctor will be ca
35720 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68 65 20  lled before the 
35730 6d 65 74 61 64 61 74 61 20 69 73 20 64 72 6f 70  metadata is drop
35740 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ped..**.** ^(In 
35750 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61  practice, metada
35760 74 61 20 69 73 20 70 72 65 73 65 72 76 65 64 20  ta is preserved 
35770 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e  between function
35780 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 65 78   calls for.** ex
35790 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74 20 61  pressions that a
357a0 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74 20 63  re constant at c
357b0 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54 68 69  ompile time. Thi
357c0 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74 65 72  s includes liter
357d0 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
357e0 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e 29 5e   [parameters].)^
357f0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
35800 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
35810 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
35820 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
35830 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  ch.** the SQL fu
35840 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
35850 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
35860 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 67   void *sqlite3_g
35870 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74  et_auxdata(sqlit
35880 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
35890 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20   N);.SQLITE_API 
358a0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
358b0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
358c0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
358d0 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
358e0 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
358f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
35900 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
35910 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
35920 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
35930 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
35940 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
35950 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
35960 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
35970 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
35980 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
35990 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
359a0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
359b0 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
359c0 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
359d0 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
359e0 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
359f0 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
35a00 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
35a10 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
35a20 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
35a30 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
35a40 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
35a50 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
35a60 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
35a70 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
35a80 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
35a90 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
35aa0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
35ab0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
35ac0 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
35ad0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
35ae0 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
35af0 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
35b00 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
35b10 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
35b20 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
35b30 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
35b40 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
35b50 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
35b60 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
35b70 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
35b80 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
35b90 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
35ba0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
35bb0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
35bc0 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
35bd0 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
35be0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
35bf0 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
35c00 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
35c10 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35c20 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
35c30 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
35c40 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
35c50 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
35c60 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
35c70 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
35c80 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
35c90 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
35ca0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
35cb0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
35cc0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35cd0 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
35ce0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
35cf0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
35d00 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
35d10 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
35d20 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
35d30 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
35d40 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
35d50 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
35d60 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
35d70 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
35d80 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
35d90 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
35da0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35db0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
35dc0 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
35dd0 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
35de0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
35df0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
35e00 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
35e10 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
35e20 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
35e30 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
35e40 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
35e50 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35e60 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
35e70 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
35e80 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
35e90 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
35ea0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
35eb0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
35ec0 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
35ed0 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
35ee0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
35ef0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
35f00 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
35f10 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
35f20 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
35f30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
35f40 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
35f50 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
35f60 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
35f70 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
35f80 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
35f90 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
35fa0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
35fb0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
35fc0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
35fd0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
35fe0 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
35ff0 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
36000 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36010 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
36020 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
36030 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
36040 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
36050 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
36060 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36070 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
36080 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36090 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
360a0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
360b0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
360c0 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
360d0 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
360e0 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
360f0 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
36100 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
36110 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
36120 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36130 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
36140 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
36150 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
36160 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
36170 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
36180 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
36190 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
361a0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
361b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
361c0 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
361d0 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
361e0 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
361f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36200 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
36210 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
36220 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
36230 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
36240 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
36250 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
36260 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
36270 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
36280 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
36290 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
362a0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
362b0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
362c0 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
362d0 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
362e0 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
362f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
36300 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36310 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
36320 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36330 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
36340 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
36350 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
36360 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
36370 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
36380 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
36390 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
363a0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
363b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
363c0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
363d0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
363e0 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
363f0 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
36400 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
36410 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
36420 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
36430 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
36440 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
36450 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
36460 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
36470 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
36480 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
36490 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
364a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
364b0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
364c0 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
364d0 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
364e0 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
364f0 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
36500 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
36510 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
36520 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
36530 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
36540 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
36550 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
36560 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
36570 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
36580 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36590 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
365a0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
365b0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
365c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
365d0 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28  3_result_toobig(
365e0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
365f0 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
36600 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
36610 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
36620 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
36630 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
36640 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
36650 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36660 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
36670 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
36680 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
36690 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
366a0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
366b0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
366c0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
366d0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
366e0 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
366f0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
36700 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
36710 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36720 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36730 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
36740 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
36750 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
36760 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
36770 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36780 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
36790 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
367a0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
367b0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
367c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
367d0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
367e0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
367f0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
36800 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
36810 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
36820 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36830 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
36840 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
36850 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
36860 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36870 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36880 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
36890 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
368a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
368b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
368c0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
368d0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
368e0 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
368f0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
36900 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
36910 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
36920 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
36930 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36940 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36950 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
36960 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
36970 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
36980 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
36990 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
369a0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
369b0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
369c0 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
369d0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
369e0 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
369f0 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
36a00 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
36a10 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
36a20 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
36a30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
36a40 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
36a50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
36a60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
36a70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36a80 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
36a90 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
36aa0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
36ab0 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
36ac0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
36ad0 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
36ae0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
36af0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
36b00 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
36b10 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
36b20 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
36b30 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
36b40 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
36b50 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
36b60 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
36b70 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
36b80 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
36b90 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
36ba0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
36bb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36bc0 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
36bd0 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74  on result.  If t
36be0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
36bf0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
36c00 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73  , then it.** mus
36c10 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
36c20 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74  fset into the st
36c30 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e  ring where the N
36c40 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
36c50 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66  uld.** appear if
36c60 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
36c70 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64  e NUL terminated
36c80 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
36c90 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a  aracters occur.*
36ca0 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  * in the string 
36cb0 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74  at a byte offset
36cc0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68   that is less th
36cd0 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  an the value of 
36ce0 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d  the 3rd.** param
36cf0 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  eter, then the r
36d00 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
36d10 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62  will contain emb
36d20 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74  edded NULs and t
36d30 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20  he.** result of 
36d40 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72  expressions oper
36d50 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73  ating on strings
36d60 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
36d70 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
36d80 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
36d90 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
36da0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36db0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
36dc0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
36dd0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
36de0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
36df0 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
36e00 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
36e10 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
36e20 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
36e30 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
36e40 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
36e50 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
36e60 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
36e70 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
36e80 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
36e90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36ea0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
36eb0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
36ec0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
36ed0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
36ee0 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
36ef0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
36f00 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
36f10 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
36f20 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
36f30 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
36f40 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
36f50 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
36f60 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
36f70 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
36f80 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
36f90 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
36fa0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
36fb0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
36fc0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
36fd0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
36fe0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36ff0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
37000 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
37010 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
37020 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
37030 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
37040 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
37050 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
37060 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
37070 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
37080 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
37090 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
370a0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
370b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
370c0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
370d0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
370e0 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
370f0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
37100 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
37110 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
37120 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
37130 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
37140 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
37150 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
37160 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
37170 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
37180 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
37190 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
371a0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
371b0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
371c0 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
371d0 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
371e0 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
371f0 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
37200 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
37210 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
37220 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
37230 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
37240 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
37250 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
37260 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
37270 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
37280 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
37290 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
372a0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
372b0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
372c0 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
372d0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
372e0 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
372f0 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
37300 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
37310 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
37320 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
37330 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
37340 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
37350 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
37360 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
37370 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37380 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
37390 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
373a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
373b0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
373c0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
373d0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
373e0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
373f0 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
37400 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
37410 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
37420 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
37430 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37440 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
37450 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
37460 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
37470 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37480 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37490 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
374a0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
374b0 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  ar*, int);.SQLIT
374c0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
374d0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
374e0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
374f0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
37500 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
37510 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37520 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
37530 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
37540 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
37550 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
37560 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
37570 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37580 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
37590 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
375a0 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
375b0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
375c0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
375d0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
375e0 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
375f0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
37600 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37610 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37620 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
37630 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
37640 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41  int64);.SQLITE_A
37650 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
37660 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
37670 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
37680 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
37690 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
376a0 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
376b0 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
376c0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
376d0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
376e0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
376f0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
37700 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37710 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
37720 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
37730 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
37740 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37750 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
37760 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
37770 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
37780 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
37790 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
377a0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
377b0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
377c0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
377d0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
377e0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
377f0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
37800 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
37810 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37820 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
37830 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
37840 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37850 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
37860 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
37870 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
37880 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
37890 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
378a0 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
378b0 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
378c0 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
378d0 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
378e0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
378f0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
37900 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
37910 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
37920 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
37930 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
37940 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
37950 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
37960 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
37970 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37980 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
37990 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
379a0 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
379b0 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
379c0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
379d0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
379e0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
379f0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
37a00 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
37a10 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
37a20 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
37a30 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
37a40 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
37a50 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
37a60 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
37a70 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
37a80 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
37a90 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
37aa0 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
37ab0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
37ac0 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
37ad0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
37ae0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
37af0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
37b00 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
37b10 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
37b20 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
37b30 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
37b40 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
37b50 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
37b60 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
37b70 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
37b80 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
37b90 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
37ba0 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
37bb0 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
37bc0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
37bd0 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
37be0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
37bf0 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
37c00 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
37c10 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
37c20 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
37c30 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
37c40 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
37c50 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
37c60 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
37c70 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
37c80 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
37c90 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
37ca0 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
37cb0 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
37cc0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
37cd0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
37ce0 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
37cf0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
37d00 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
37d10 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37d20 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
37d30 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
37d40 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
37d50 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
37d60 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
37d70 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
37d80 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
37d90 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
37da0 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
37db0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
37dc0 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
37dd0 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
37de0 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
37df0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
37e00 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
37e10 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
37e20 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
37e30 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
37e40 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
37e50 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
37e60 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
37e70 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
37e80 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
37e90 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
37ea0 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
37eb0 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
37ec0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
37ed0 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
37ee0 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
37ef0 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
37f00 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
37f10 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
37f20 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
37f30 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
37f40 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
37f50 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
37f60 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
37f70 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
37f80 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
37f90 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
37fa0 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
37fb0 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
37fc0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
37fd0 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
37fe0 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
37ff0 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
38000 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
38010 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
38020 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
38030 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
38040 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
38050 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ond,.** respecti
38060 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69  vely.  A collati
38070 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
38080 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
38090 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a  he same answer.*
380a0 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65  * given the same
380b0 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f   inputs.  If two
380c0 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69   or more collati
380d0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
380e0 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74   registered.** t
380f0 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61  o the same colla
38100 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67  tion name (using
38110 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
38120 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e  Rep values) then
38130 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76   all.** must giv
38140 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20  e an equivalent 
38150 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f  answer when invo
38160 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c  ked with equival
38170 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  ent strings..** 
38180 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
38190 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79  nction must obey
381a0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
381b0 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c  roperties for al
381c0 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20  l.** strings A, 
381d0 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20  B, and C:.**.** 
381e0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  <ol>.** <li> If 
381f0 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a  A==B then B==A..
38200 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
38210 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d  and B==C then A=
38220 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =C..** <li> If A
38230 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b  &lt;B THEN B&gt;
38240 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  A..** <li> If A&
38250 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20  lt;B and B&lt;C 
38260 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20  then A&lt;C..** 
38270 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  </ol>.**.** If a
38280 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
38290 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66  ion fails any of
382a0 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74   the above const
382b0 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a  raints and that.
382c0 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ** collating fun
382d0 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74  ction is  regist
382e0 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74  ered and used, t
382f0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
38300 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73   of SQLite.** is
38310 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
38320 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
38330 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
38340 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
38350 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
38360 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69  ollation().** wi
38370 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20  th the addition 
38380 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f  that the xDestro
38390 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  y callback is in
383a0 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68  voked on pArg wh
383b0 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  en.** the collat
383c0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
383d0 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c  deleted..** ^Col
383e0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
383f0 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65   are deleted whe
38400 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
38410 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a  idden by later.*
38420 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  * calls to the c
38430 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
38440 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
38450 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  hen the.** [data
38460 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38470 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
38480 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
38490 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
384a0 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
384b0 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63   is <u>not</u> c
384c0 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a  alled if the .**
384d0 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
384e0 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66  collation_v2() f
384f0 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  unction fails.  
38500 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
38510 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  t invoke.** sqli
38520 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
38530 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61  tion_v2() with a
38540 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72   non-NULL xDestr
38550 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  oy argument shou
38560 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65  ld .** check the
38570 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64   return code and
38580 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
38590 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
385a0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d   pointer.** them
385b0 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68  selves rather th
385c0 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c  an expecting SQL
385d0 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68  ite to deal with
385e0 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a   it for them..**
385f0 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65   This is differe
38600 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74  nt from every ot
38610 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
38620 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e  face.  The incon
38630 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20  sistency .** is 
38640 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20  unfortunate but 
38650 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
38660 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
38670 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a  ng backwards .**
38680 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
38690 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
386a0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
386b0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
386c0 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
386d0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
386e0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
386f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
38700 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20  te_collation(.  
38710 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
38720 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
38730 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
38740 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
38750 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
38760 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
38770 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
38780 20 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54   void*).);.SQLIT
38790 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
387a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 6