System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 1a89ca2701a4b54c163f32769580ebf7fb3d5f2d:


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 32 2e 20 20  ersion 3.7.12.  
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: 4d 61 6e 79 20 70 65 6f 70 6c 65 20 61 72 65 20  Many people are 
3c50: 66 61 69 6c 69 6e 67 20 74 6f 20 73 65 74 20 2d  failing to set -
3c60: 44 4e 44 45 42 55 47 3d 31 20 77 68 65 6e 20 63  DNDEBUG=1 when c
3c70: 6f 6d 70 69 6c 69 6e 67 20 53 51 4c 69 74 65 2e  ompiling SQLite.
3c80: 0a 2a 2a 20 53 65 74 74 69 6e 67 20 4e 44 45 42  .** Setting NDEB
3c90: 55 47 20 6d 61 6b 65 73 20 74 68 65 20 63 6f 64  UG makes the cod
3ca0: 65 20 73 6d 61 6c 6c 65 72 20 61 6e 64 20 72 75  e smaller and ru
3cb0: 6e 20 66 61 73 74 65 72 2e 20 20 53 6f 20 74 68  n faster.  So th
3cc0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 6c  e following.** l
3cd0: 69 6e 65 73 20 61 72 65 20 61 64 64 65 64 20 74  ines are added t
3ce0: 6f 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  o automatically 
3cf0: 73 65 74 20 4e 44 45 42 55 47 20 75 6e 6c 65 73  set NDEBUG unles
3d00: 73 20 74 68 65 20 2d 44 53 51 4c 49 54 45 5f 44  s the -DSQLITE_D
3d10: 45 42 55 47 3d 31 0a 2a 2a 20 6f 70 74 69 6f 6e  EBUG=1.** option
3d20: 20 69 73 20 73 65 74 2e 20 20 54 68 75 73 20 4e   is set.  Thus N
3d30: 44 45 42 55 47 20 62 65 63 6f 6d 65 73 20 61 6e  DEBUG becomes an
3d40: 20 6f 70 74 2d 69 6e 20 72 61 74 68 65 72 20 74   opt-in rather t
3d50: 68 61 6e 20 61 6e 20 6f 70 74 2d 6f 75 74 0a 2a  han an opt-out.*
3d60: 2a 20 66 65 61 74 75 72 65 2e 0a 2a 2f 0a 23 69  * feature..*/.#i
3d70: 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42 55  f !defined(NDEBU
3d80: 47 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 53  G) && !defined(S
3d90: 51 4c 49 54 45 5f 44 45 42 55 47 29 20 0a 23 20  QLITE_DEBUG) .# 
3da0: 64 65 66 69 6e 65 20 4e 44 45 42 55 47 20 31 0a  define NDEBUG 1.
3db0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68  #endif../*.** Th
3dc0: 65 20 74 65 73 74 63 61 73 65 28 29 20 6d 61 63  e testcase() mac
3dd0: 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20 61 69  ro is used to ai
3de0: 64 20 69 6e 20 63 6f 76 65 72 61 67 65 20 74 65  d in coverage te
3df0: 73 74 69 6e 67 2e 20 20 57 68 65 6e 20 0a 2a 2a  sting.  When .**
3e00: 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 20   doing coverage 
3e10: 74 65 73 74 69 6e 67 2c 20 74 68 65 20 63 6f 6e  testing, the con
3e20: 64 69 74 69 6f 6e 20 69 6e 73 69 64 65 20 74 68  dition inside th
3e30: 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  e argument to.**
3e40: 20 74 65 73 74 63 61 73 65 28 29 20 6d 75 73 74   testcase() must
3e50: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 62 6f   be evaluated bo
3e60: 74 68 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73  th true and fals
3e70: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a  e in order to.**
3e80: 20 67 65 74 20 66 75 6c 6c 20 62 72 61 6e 63 68   get full branch
3e90: 20 63 6f 76 65 72 61 67 65 2e 20 20 54 68 65 20   coverage.  The 
3ea0: 74 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 6f  testcase() macro
3eb0: 20 69 73 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20   is inserted.** 
3ec0: 74 6f 20 68 65 6c 70 20 65 6e 73 75 72 65 20 61  to help ensure a
3ed0: 64 65 71 75 61 74 65 20 74 65 73 74 20 63 6f 76  dequate test cov
3ee0: 65 72 61 67 65 20 69 6e 20 70 6c 61 63 65 73 20  erage in places 
3ef0: 77 68 65 72 65 20 73 69 6d 70 6c 65 0a 2a 2a 20  where simple.** 
3f00: 63 6f 6e 64 69 74 69 6f 6e 2f 64 65 63 69 73 69  condition/decisi
3f10: 6f 6e 20 63 6f 76 65 72 61 67 65 20 69 73 20 69  on coverage is i
3f20: 6e 61 64 65 71 75 61 74 65 2e 20 20 46 6f 72 20  nadequate.  For 
3f30: 65 78 61 6d 70 6c 65 2c 20 74 65 73 74 63 61 73  example, testcas
3f40: 65 28 29 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  e().** can be us
3f50: 65 64 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  ed to make sure 
3f60: 62 6f 75 6e 64 61 72 79 20 76 61 6c 75 65 73 20  boundary values 
3f70: 61 72 65 20 74 65 73 74 65 64 2e 20 20 46 6f 72  are tested.  For
3f80: 0a 2a 2a 20 62 69 74 6d 61 73 6b 20 74 65 73 74  .** bitmask test
3f90: 73 2c 20 74 65 73 74 63 61 73 65 28 29 20 63 61  s, testcase() ca
3fa0: 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6d 61 6b  n be used to mak
3fb0: 65 20 73 75 72 65 20 65 61 63 68 20 62 69 74 0a  e sure each bit.
3fc0: 2a 2a 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e  ** is significan
3fd0: 74 20 61 6e 64 20 75 73 65 64 20 61 74 20 6c 65  t and used at le
3fe0: 61 73 74 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 77  ast once.  On sw
3ff0: 69 74 63 68 20 73 74 61 74 65 6d 65 6e 74 73 0a  itch statements.
4000: 2a 2a 20 77 68 65 72 65 20 6d 75 6c 74 69 70 6c  ** where multipl
4010: 65 20 63 61 73 65 73 20 67 6f 20 74 6f 20 74 68  e cases go to th
4020: 65 20 73 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20  e same block of 
4030: 63 6f 64 65 2c 20 74 65 73 74 63 61 73 65 28 29  code, testcase()
4040: 0a 2a 2a 20 63 61 6e 20 69 6e 73 75 72 65 20 74  .** can insure t
4050: 68 61 74 20 61 6c 6c 20 63 61 73 65 73 20 61 72  hat all cases ar
4060: 65 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a  e evaluated..**.
4070: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
4080: 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 0a 53  _COVERAGE_TEST.S
4090: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 20 20  QLITE_PRIVATE   
40a0: 76 6f 69 64 20 73 71 6c 69 74 65 33 43 6f 76 65  void sqlite3Cove
40b0: 72 61 67 65 28 69 6e 74 29 3b 0a 23 20 64 65 66  rage(int);.# def
40c0: 69 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 20  ine testcase(X) 
40d0: 20 69 66 28 20 58 20 29 7b 20 73 71 6c 69 74 65   if( X ){ sqlite
40e0: 33 43 6f 76 65 72 61 67 65 28 5f 5f 4c 49 4e 45  3Coverage(__LINE
40f0: 5f 5f 29 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 64  __); }.#else.# d
4100: 65 66 69 6e 65 20 74 65 73 74 63 61 73 65 28 58  efine testcase(X
4110: 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ).#endif../*.** 
4120: 54 68 65 20 54 45 53 54 4f 4e 4c 59 20 6d 61 63  The TESTONLY mac
4130: 72 6f 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  ro is used to en
4140: 63 6c 6f 73 65 20 76 61 72 69 61 62 6c 65 20 64  close variable d
4150: 65 63 6c 61 72 61 74 69 6f 6e 73 20 6f 72 0a 2a  eclarations or.*
4160: 2a 20 6f 74 68 65 72 20 62 69 74 73 20 6f 66 20  * other bits of 
4170: 63 6f 64 65 20 74 68 61 74 20 61 72 65 20 6e 65  code that are ne
4180: 65 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20  eded to support 
4190: 74 68 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  the arguments.**
41a0: 20 77 69 74 68 69 6e 20 74 65 73 74 63 61 73 65   within testcase
41b0: 28 29 20 61 6e 64 20 61 73 73 65 72 74 28 29 20  () and assert() 
41c0: 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 21  macros..*/.#if !
41d0: 64 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29 20  defined(NDEBUG) 
41e0: 7c 7c 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54  || defined(SQLIT
41f0: 45 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 29  E_COVERAGE_TEST)
4200: 0a 23 20 64 65 66 69 6e 65 20 54 45 53 54 4f 4e  .# define TESTON
4210: 4c 59 28 58 29 20 20 58 0a 23 65 6c 73 65 0a 23  LY(X)  X.#else.#
4220: 20 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59   define TESTONLY
4230: 28 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  (X).#endif../*.*
4240: 2a 20 53 6f 6d 65 74 69 6d 65 73 20 77 65 20 6e  * Sometimes we n
4250: 65 65 64 20 61 20 73 6d 61 6c 6c 20 61 6d 6f 75  eed a small amou
4260: 6e 74 20 6f 66 20 63 6f 64 65 20 73 75 63 68 20  nt of code such 
4270: 61 73 20 61 20 76 61 72 69 61 62 6c 65 20 69 6e  as a variable in
4280: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a 20  itialization.** 
4290: 74 6f 20 73 65 74 75 70 20 66 6f 72 20 61 20 6c  to setup for a l
42a0: 61 74 65 72 20 61 73 73 65 72 74 28 29 20 73 74  ater assert() st
42b0: 61 74 65 6d 65 6e 74 2e 20 20 57 65 20 64 6f 20  atement.  We do 
42c0: 6e 6f 74 20 77 61 6e 74 20 74 68 69 73 20 63 6f  not want this co
42d0: 64 65 20 74 6f 0a 2a 2a 20 61 70 70 65 61 72 20  de to.** appear 
42e0: 77 68 65 6e 20 61 73 73 65 72 74 28 29 20 69 73  when assert() is
42f0: 20 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20   disabled.  The 
4300: 66 6f 6c 6c 6f 77 69 6e 67 20 6d 61 63 72 6f 20  following macro 
4310: 69 73 20 74 68 65 72 65 66 6f 72 65 0a 2a 2a 20  is therefore.** 
4320: 75 73 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20  used to contain 
4330: 74 68 61 74 20 73 65 74 75 70 20 63 6f 64 65 2e  that setup code.
4340: 20 20 54 68 65 20 22 56 56 41 22 20 61 63 72 6f    The "VVA" acro
4350: 6e 79 6d 20 73 74 61 6e 64 73 20 66 6f 72 0a 2a  nym stands for.*
4360: 2a 20 22 56 65 72 69 66 69 63 61 74 69 6f 6e 2c  * "Verification,
4370: 20 56 61 6c 69 64 61 74 69 6f 6e 2c 20 61 6e 64   Validation, and
4380: 20 41 63 63 72 65 64 69 74 61 74 69 6f 6e 22 2e   Accreditation".
4390: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
43a0: 2c 20 74 68 65 0a 2a 2a 20 63 6f 64 65 20 77 69  , the.** code wi
43b0: 74 68 69 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 20  thin VVA_ONLY() 
43c0: 77 69 6c 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 75  will only run du
43d0: 72 69 6e 67 20 76 65 72 69 66 69 63 61 74 69 6f  ring verificatio
43e0: 6e 20 70 72 6f 63 65 73 73 65 73 2e 0a 2a 2f 0a  n processes..*/.
43f0: 23 69 66 6e 64 65 66 20 4e 44 45 42 55 47 0a 23  #ifndef NDEBUG.#
4400: 20 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59   define VVA_ONLY
4410: 28 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 64  (X)  X.#else.# d
4420: 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58  efine VVA_ONLY(X
4430: 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  ).#endif../*.** 
4440: 54 68 65 20 41 4c 57 41 59 53 20 61 6e 64 20 4e  The ALWAYS and N
4450: 45 56 45 52 20 6d 61 63 72 6f 73 20 73 75 72 72  EVER macros surr
4460: 6f 75 6e 64 20 62 6f 6f 6c 65 61 6e 20 65 78 70  ound boolean exp
4470: 72 65 73 73 69 6f 6e 73 20 77 68 69 63 68 20 0a  ressions which .
4480: 2a 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  ** are intended 
4490: 74 6f 20 61 6c 77 61 79 73 20 62 65 20 74 72 75  to always be tru
44a0: 65 20 6f 72 20 66 61 6c 73 65 2c 20 72 65 73 70  e or false, resp
44b0: 65 63 74 69 76 65 6c 79 2e 20 20 53 75 63 68 0a  ectively.  Such.
44c0: 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63  ** expressions c
44d0: 6f 75 6c 64 20 62 65 20 6f 6d 69 74 74 65 64 20  ould be omitted 
44e0: 66 72 6f 6d 20 74 68 65 20 63 6f 64 65 20 63 6f  from the code co
44f0: 6d 70 6c 65 74 65 6c 79 2e 20 20 42 75 74 20 74  mpletely.  But t
4500: 68 65 79 0a 2a 2a 20 61 72 65 20 69 6e 63 6c 75  hey.** are inclu
4510: 64 65 64 20 69 6e 20 61 20 66 65 77 20 63 61 73  ded in a few cas
4520: 65 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65  es in order to e
4530: 6e 68 61 6e 63 65 20 74 68 65 20 72 65 73 69 6c  nhance the resil
4540: 69 65 6e 63 65 0a 2a 2a 20 6f 66 20 53 51 4c 69  ience.** of SQLi
4550: 74 65 20 74 6f 20 75 6e 65 78 70 65 63 74 65 64  te to unexpected
4560: 20 62 65 68 61 76 69 6f 72 20 2d 20 74 6f 20 6d   behavior - to m
4570: 61 6b 65 20 74 68 65 20 63 6f 64 65 20 22 73 65  ake the code "se
4580: 6c 66 2d 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 6f  lf-healing".** o
4590: 72 20 22 64 75 63 74 69 6c 65 22 20 72 61 74 68  r "ductile" rath
45a0: 65 72 20 74 68 61 6e 20 62 65 69 6e 67 20 22 62  er than being "b
45b0: 72 69 74 74 6c 65 22 20 61 6e 64 20 63 72 61 73  rittle" and cras
45c0: 68 69 6e 67 20 61 74 20 74 68 65 20 66 69 72 73  hing at the firs
45d0: 74 0a 2a 2a 20 68 69 6e 74 20 6f 66 20 75 6e 70  t.** hint of unp
45e0: 6c 61 6e 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  lanned behavior.
45f0: 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
4600: 77 6f 72 64 73 2c 20 41 4c 57 41 59 53 20 61 6e  words, ALWAYS an
4610: 64 20 4e 45 56 45 52 20 61 72 65 20 61 64 64 65  d NEVER are adde
4620: 64 20 66 6f 72 20 64 65 66 65 6e 73 69 76 65 20  d for defensive 
4630: 63 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  code..**.** When
4640: 20 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 20   doing coverage 
4650: 74 65 73 74 69 6e 67 20 41 4c 57 41 59 53 20 61  testing ALWAYS a
4660: 6e 64 20 4e 45 56 45 52 20 61 72 65 20 68 61 72  nd NEVER are har
4670: 64 2d 63 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 65  d-coded to.** be
4680: 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 20   true and false 
4690: 73 6f 20 74 68 61 74 20 74 68 65 20 75 6e 72 65  so that the unre
46a0: 61 63 68 61 62 6c 65 20 63 6f 64 65 20 74 68 65  achable code the
46b0: 6e 20 73 70 65 63 69 66 79 20 77 69 6c 6c 0a 2a  n specify will.*
46c0: 2a 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64  * not be counted
46d0: 20 61 73 20 75 6e 74 65 73 74 65 64 20 63 6f 64   as untested cod
46e0: 65 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  e..*/.#if define
46f0: 64 28 53 51 4c 49 54 45 5f 43 4f 56 45 52 41 47  d(SQLITE_COVERAG
4700: 45 5f 54 45 53 54 29 0a 23 20 64 65 66 69 6e 65  E_TEST).# define
4710: 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20   ALWAYS(X)      
4720: 28 31 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56  (1).# define NEV
4730: 45 52 28 58 29 20 20 20 20 20 20 20 28 30 29 0a  ER(X)       (0).
4740: 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 4e  #elif !defined(N
4750: 44 45 42 55 47 29 0a 23 20 64 65 66 69 6e 65 20  DEBUG).# define 
4760: 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28  ALWAYS(X)      (
4770: 28 58 29 3f 31 3a 28 61 73 73 65 72 74 28 30 29  (X)?1:(assert(0)
4780: 2c 30 29 29 0a 23 20 64 65 66 69 6e 65 20 4e 45  ,0)).# define NE
4790: 56 45 52 28 58 29 20 20 20 20 20 20 20 28 28 58  VER(X)       ((X
47a0: 29 3f 28 61 73 73 65 72 74 28 30 29 2c 31 29 3a  )?(assert(0),1):
47b0: 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  0).#else.# defin
47c0: 65 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20  e ALWAYS(X)     
47d0: 20 28 58 29 0a 23 20 64 65 66 69 6e 65 20 4e 45   (X).# define NE
47e0: 56 45 52 28 58 29 20 20 20 20 20 20 20 28 58 29  VER(X)       (X)
47f0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 52  .#endif../*.** R
4800: 65 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d  eturn true (non-
4810: 7a 65 72 6f 29 20 69 66 20 74 68 65 20 69 6e 70  zero) if the inp
4820: 75 74 20 69 73 20 61 20 69 6e 74 65 67 65 72 20  ut is a integer 
4830: 74 68 61 74 20 69 73 20 74 6f 6f 20 6c 61 72 67  that is too larg
4840: 65 0a 2a 2a 20 74 6f 20 66 69 74 20 69 6e 20 33  e.** to fit in 3
4850: 32 2d 62 69 74 73 2e 20 20 54 68 69 73 20 6d 61  2-bits.  This ma
4860: 63 72 6f 20 69 73 20 75 73 65 64 20 69 6e 73 69  cro is used insi
4870: 64 65 20 6f 66 20 76 61 72 69 6f 75 73 20 74 65  de of various te
4880: 73 74 63 61 73 65 28 29 0a 2a 2a 20 6d 61 63 72  stcase().** macr
4890: 6f 73 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  os to verify tha
48a0: 74 20 77 65 20 68 61 76 65 20 74 65 73 74 65 64  t we have tested
48b0: 20 53 51 4c 69 74 65 20 66 6f 72 20 6c 61 72 67   SQLite for larg
48c0: 65 2d 66 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a  e-file support..
48d0: 2a 2f 0a 23 64 65 66 69 6e 65 20 49 53 5f 42 49  */.#define IS_BI
48e0: 47 5f 49 4e 54 28 58 29 20 20 28 28 28 58 29 26  G_INT(X)  (((X)&
48f0: 7e 28 69 36 34 29 30 78 66 66 66 66 66 66 66 66  ~(i64)0xffffffff
4900: 29 21 3d 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  )!=0)../*.** The
4910: 20 6d 61 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 28   macro unlikely(
4920: 29 20 69 73 20 61 20 68 69 6e 74 20 74 68 61 74  ) is a hint that
4930: 20 73 75 72 72 6f 75 6e 64 73 20 61 20 62 6f 6f   surrounds a boo
4940: 6c 65 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69  lean.** expressi
4950: 6f 6e 20 74 68 61 74 20 69 73 20 75 73 75 61 6c  on that is usual
4960: 6c 79 20 66 61 6c 73 65 2e 20 20 4d 61 63 72 6f  ly false.  Macro
4970: 20 6c 69 6b 65 6c 79 28 29 20 73 75 72 72 6f 75   likely() surrou
4980: 6e 64 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e  nds.** a boolean
4990: 20 65 78 70 72 65 73 73 69 6f 6e 20 74 68 61 74   expression that
49a0: 20 69 73 20 75 73 75 61 6c 6c 79 20 74 72 75 65   is usually true
49b0: 2e 20 20 47 43 43 20 69 73 20 61 62 6c 65 20 74  .  GCC is able t
49c0: 6f 0a 2a 2a 20 75 73 65 20 74 68 65 73 65 20 68  o.** use these h
49d0: 69 6e 74 73 20 74 6f 20 67 65 6e 65 72 61 74 65  ints to generate
49e0: 20 62 65 74 74 65 72 20 63 6f 64 65 2c 20 73 6f   better code, so
49f0: 6d 65 74 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 20  metimes..*/.#if 
4a00: 64 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f  defined(__GNUC__
4a10: 29 20 26 26 20 30 0a 23 20 64 65 66 69 6e 65 20  ) && 0.# define 
4a20: 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 5f 5f 62  likely(X)    __b
4a30: 75 69 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 58  uiltin_expect((X
4a40: 29 2c 31 29 0a 23 20 64 65 66 69 6e 65 20 75 6e  ),1).# define un
4a50: 6c 69 6b 65 6c 79 28 58 29 20 20 5f 5f 62 75 69  likely(X)  __bui
4a60: 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 2c  ltin_expect((X),
4a70: 30 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e  0).#else.# defin
4a80: 65 20 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 21  e likely(X)    !
4a90: 21 28 58 29 0a 23 20 64 65 66 69 6e 65 20 75 6e  !(X).# define un
4aa0: 6c 69 6b 65 6c 79 28 58 29 20 20 21 21 28 58 29  likely(X)  !!(X)
4ab0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a  .#endif../******
4ac0: 2a 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65  ******** Include
4ad0: 20 73 71 6c 69 74 65 33 2e 68 20 69 6e 20 74 68   sqlite3.h in th
4ae0: 65 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69  e middle of sqli
4af0: 74 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a  teInt.h ********
4b00: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  *******/./******
4b10: 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66  ******** Begin f
4b20: 69 6c 65 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a  ile sqlite3.h **
4b30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b40: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4b50: 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32  *******/./*.** 2
4b60: 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35  001 September 15
4b70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  .**.** The autho
4b80: 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79  r disclaims copy
4b90: 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f  right to this so
4ba0: 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70  urce code.  In p
4bb0: 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67  lace of.** a leg
4bc0: 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20  al notice, here 
4bd0: 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a  is a blessing:.*
4be0: 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20  *.**    May you 
4bf0: 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20  do good and not 
4c00: 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  evil..**    May 
4c10: 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65  you find forgive
4c20: 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c  ness for yoursel
4c30: 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74  f and forgive ot
4c40: 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20  hers..**    May 
4c50: 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79  you share freely
4c60: 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d  , never taking m
4c70: 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76  ore than you giv
4c80: 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  e..**.**********
4c90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ca0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4cb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4cc0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
4cd0: 2a 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66  ** This header f
4ce0: 69 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20  ile defines the 
4cf0: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74  interface that t
4d00: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
4d10: 79 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f  y.** presents to
4d20: 20 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73   client programs
4d30: 2e 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69  .  If a C-functi
4d40: 6f 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64  on, structure, d
4d50: 61 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63  atatype,.** or c
4d60: 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69  onstant definiti
4d70: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65  on does not appe
4d80: 61 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c  ar in this file,
4d90: 20 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e   then it is.** n
4da0: 6f 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41  ot a published A
4db0: 50 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73  PI of SQLite, is
4dc0: 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
4dd0: 67 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f  ge without.** no
4de0: 74 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64  tice, and should
4df0: 20 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63   not be referenc
4e00: 65 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74  ed by programs t
4e10: 68 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a  hat use SQLite..
4e20: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
4e30: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68  e definitions th
4e40: 61 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66  at are in this f
4e50: 69 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61  ile are marked a
4e60: 73 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74  s.** "experiment
4e70: 61 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74  al".  Experiment
4e80: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  al interfaces ar
4e90: 65 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a  e normally new.*
4ea0: 2a 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e  * features recen
4eb0: 74 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c  tly added to SQL
4ec0: 69 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20  ite.  We do not 
4ed0: 61 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67  anticipate chang
4ee0: 65 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d  es.** to experim
4ef0: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
4f00: 20 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65   but reserve the
4f10: 20 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d   right to make m
4f20: 69 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  inor changes.** 
4f30: 69 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72  if experience fr
4f40: 6f 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77  om use "in the w
4f50: 69 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63  ild" suggest suc
4f60: 68 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72  h changes are pr
4f70: 75 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  udent..**.** The
4f80: 20 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67   official C-lang
4f90: 75 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e  uage API documen
4fa0: 74 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74  tation for SQLit
4fb0: 65 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20  e is derived.** 
4fc0: 66 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e  from comments in
4fd0: 20 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69   this file.  Thi
4fe0: 73 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75  s file is the au
4ff0: 74 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72  thoritative sour
5000: 63 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c  ce.** on how SQL
5010: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
5020: 72 65 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70  re suppose to op
5030: 65 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  erate..**.** The
5040: 20 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69   name of this fi
5050: 6c 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75  le under configu
5060: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
5070: 74 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69  t is "sqlite.h.i
5080: 6e 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66  n"..** The makef
5090: 69 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d  ile makes some m
50a0: 69 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20  inor changes to 
50b0: 74 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 20  this file (such 
50c0: 61 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20  as inserting.** 
50d0: 74 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  the version numb
50e0: 65 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20  er) and changes 
50f0: 69 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c  its name to "sql
5100: 69 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61  ite3.h" as.** pa
5110: 72 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20  rt of the build 
5120: 70 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e  process..*/.#ifn
5130: 64 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a  def _SQLITE3_H_.
5140: 23 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33  #define _SQLITE3
5150: 5f 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74  _H_.#include <st
5160: 64 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e  darg.h>     /* N
5170: 65 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65  eeded for the de
5180: 66 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c  finition of va_l
5190: 69 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61  ist */../*.** Ma
51a0: 6b 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63  ke sure we can c
51b0: 61 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66  all this stuff f
51c0: 72 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20  rom C++..*/.#if 
51d0: 30 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23  0.extern "C" {.#
51e0: 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64  endif.../*.** Ad
51f0: 64 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f  d the ability to
5200: 20 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72   override 'exter
5210: 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  n'.*/.#ifndef SQ
5220: 4c 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65  LITE_EXTERN.# de
5230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45  fine SQLITE_EXTE
5240: 52 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66  RN extern.#endif
5250: 0a 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45  ..#ifndef SQLITE
5260: 5f 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51  _API.# define SQ
5270: 4c 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a  LITE_API.#endif.
5280: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f  ../*.** These no
5290: 2d 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75  -op macros are u
52a0: 73 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20  sed in front of 
52b0: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61  interfaces to ma
52c0: 72 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65  rk those.** inte
52d0: 72 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72  rfaces as either
52e0: 20 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65   deprecated or e
52f0: 78 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65  xperimental.  Ne
5300: 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  w applications.*
5310: 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65  * should not use
5320: 20 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65   deprecated inte
5330: 72 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72  rfaces - they ar
5340: 65 20 73 75 70 70 6f 72 74 20 66 6f 72 20 62 61  e support for ba
5350: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
5360: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20  tibility only.  
5370: 41 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74  Application writ
5380: 65 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77  ers should be aw
5390: 61 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65  are that.** expe
53a0: 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61  rimental interfa
53b0: 63 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 20  ces are subject 
53c0: 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69  to change in poi
53d0: 6e 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a  nt releases..**.
53e0: 2a 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20  ** These macros 
53f0: 75 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20  used to resolve 
5400: 74 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73  to various kinds
5410: 20 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67   of compiler mag
5420: 69 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64  ic that.** would
5430: 20 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e   generate warnin
5440: 67 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20  g messages when 
5450: 74 68 65 79 20 77 65 72 65 20 75 73 65 64 2e 20  they were used. 
5460: 20 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d   But that.** com
5470: 70 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65  piler magic ende
5480: 64 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20  d up generating 
5490: 73 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66  such a flurry of
54a0: 20 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20   bug reports.** 
54b0: 74 68 61 74 20 77 65 20 68 61 76 65 20 74 61 6b  that we have tak
54c0: 65 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e  en it all out an
54d0: 64 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75  d gone back to u
54e0: 73 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e  sing simple.** n
54f0: 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23  oop macros..*/.#
5500: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
5510: 50 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65  PRECATED.#define
5520: 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45   SQLITE_EXPERIME
5530: 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75  NTAL../*.** Ensu
5540: 72 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73  re these symbols
5550: 20 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65   were not define
5560: 64 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f  d by some previo
5570: 75 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a  us header file..
5580: 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  */.#ifdef SQLITE
5590: 5f 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66  _VERSION.# undef
55a0: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a   SQLITE_VERSION.
55b0: 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51  #endif.#ifdef SQ
55c0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d  LITE_VERSION_NUM
55d0: 42 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49  BER.# undef SQLI
55e0: 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45  TE_VERSION_NUMBE
55f0: 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  R.#endif../*.** 
5600: 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
5610: 65 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56  e-Time Library V
5620: 65 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a  ersion Numbers.*
5630: 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49  *.** ^(The [SQLI
5640: 54 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 72  TE_VERSION] C pr
5650: 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
5660: 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e   in the sqlite3.
5670: 68 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c  h header.** eval
5680: 75 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 6e  uates to a strin
5690: 67 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69  g literal that i
56a0: 73 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72  s the SQLite ver
56b0: 73 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66  sion in the.** f
56c0: 6f 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 68  ormat "X.Y.Z" wh
56d0: 65 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 6a  ere X is the maj
56e0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
56f0: 72 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 0a  r (always 3 for.
5700: 2a 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 20  ** SQLite3) and 
5710: 59 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76  Y is the minor v
5720: 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e  ersion number an
5730: 64 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 61  d Z is the relea
5740: 73 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20  se number.)^.** 
5750: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45  ^(The [SQLITE_VE
5760: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20  RSION_NUMBER] C 
5770: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
5780: 72 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61  ro resolves to a
5790: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74  n integer.** wit
57a0: 68 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31  h the value (X*1
57b0: 30 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20  000000 + Y*1000 
57c0: 2b 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c  + Z) where X, Y,
57d0: 20 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 73   and Z are the s
57e0: 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75  ame.** numbers u
57f0: 73 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56  sed in [SQLITE_V
5800: 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68  ERSION].)^.** Th
5810: 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  e SQLITE_VERSION
5820: 5f 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 20  _NUMBER for any 
5830: 67 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f 66  given release of
5840: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73   SQLite will als
5850: 6f 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 74  o.** be larger t
5860: 68 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 20  han the release 
5870: 66 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 73  from which it is
5880: 20 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 65   derived.  Eithe
5890: 72 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68  r Y will.** be h
58a0: 65 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64  eld constant and
58b0: 20 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65   Z will be incre
58c0: 6d 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 59  mented or else Y
58d0: 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65   will be increme
58e0: 6e 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69  nted.** and Z wi
58f0: 6c 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 7a  ll be reset to z
5900: 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65  ero..**.** Since
5910: 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c   version 3.6.18,
5920: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63   SQLite source c
5930: 6f 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f  ode has been sto
5940: 72 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61  red in the.** <a
5950: 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77   href="http://ww
5960: 77 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67  w.fossil-scm.org
5970: 2f 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67  /">Fossil config
5980: 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65  uration manageme
5990: 6e 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e  nt.** system</a>
59a0: 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53  .  ^The SQLITE_S
59b0: 4f 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65  OURCE_ID macro e
59c0: 76 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61  valuates to.** a
59d0: 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64   string which id
59e0: 65 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69  entifies a parti
59f0: 63 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f  cular check-in o
5a00: 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68  f SQLite.** with
5a10: 69 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61  in its configura
5a20: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20  tion management 
5a30: 73 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51  system.  ^The SQ
5a40: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a  LITE_SOURCE_ID.*
5a50: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
5a60: 73 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74  s the date and t
5a70: 69 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b  ime of the check
5a80: 2d 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e  -in (UTC) and an
5a90: 20 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66   SHA1.** hash of
5aa0: 20 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72   the entire sour
5ab0: 63 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53  ce tree..**.** S
5ac0: 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
5ad0: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c  3_libversion()],
5ae0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62  .** [sqlite3_lib
5af0: 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29  version_number()
5b00: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72  ], [sqlite3_sour
5b10: 63 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  ceid()],.** [sql
5b20: 69 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61  ite_version()] a
5b30: 6e 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63  nd [sqlite_sourc
5b40: 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  e_id()]..*/.#def
5b50: 69 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49  ine SQLITE_VERSI
5b60: 4f 4e 20 20 20 20 20 20 20 20 22 33 2e 37 2e 31  ON        "3.7.1
5b70: 32 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  2".#define SQLIT
5b80: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
5b90: 20 33 30 30 37 30 31 32 0a 23 64 65 66 69 6e 65   3007012.#define
5ba0: 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49   SQLITE_SOURCE_I
5bb0: 44 20 20 20 20 20 20 22 32 30 31 32 2d 30 35 2d  D      "2012-05-
5bc0: 31 32 20 31 38 3a 32 39 3a 35 33 20 65 35 33 36  12 18:29:53 e536
5bd0: 61 63 30 34 31 38 31 35 62 31 31 38 63 34 36 31  ac041815b118c461
5be0: 63 65 65 65 37 39 38 66 39 62 37 32 38 33 32 36  ceee798f9b728326
5bf0: 39 66 35 38 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  9f58"../*.** CAP
5c00: 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20  I3REF: Run-Time 
5c10: 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20  Library Version 
5c20: 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f  Numbers.** KEYWO
5c30: 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72  RDS: sqlite3_ver
5c40: 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f  sion, sqlite3_so
5c50: 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65  urceid.**.** The
5c60: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72  se interfaces pr
5c70: 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69  ovide the same i
5c80: 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68  nformation as th
5c90: 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  e [SQLITE_VERSIO
5ca0: 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56  N],.** [SQLITE_V
5cb0: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20  ERSION_NUMBER], 
5cc0: 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52  and [SQLITE_SOUR
5cd0: 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63  CE_ID] C preproc
5ce0: 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20  essor macros.** 
5cf0: 62 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74  but are associat
5d00: 65 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72  ed with the libr
5d10: 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74  ary instead of t
5d20: 68 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20  he header file. 
5d30: 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70   ^(Cautious.** p
5d40: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
5d50: 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28   include assert(
5d60: 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  ) statements in 
5d70: 74 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f  their applicatio
5d80: 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74  n to.** verify t
5d90: 68 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72  hat values retur
5da0: 6e 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74  ned by these int
5db0: 65 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68  erfaces match th
5dc0: 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74  e macros in.** t
5dd0: 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74  he header, and t
5de0: 68 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20  hus insure that 
5df0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
5e00: 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
5e10: 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62  ith matching lib
5e20: 72 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20  rary and header 
5e30: 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c  files..**.** <bl
5e40: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
5e50: 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65  * assert( sqlite
5e60: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
5e70: 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45  ber()==SQLITE_VE
5e80: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a  RSION_NUMBER );.
5e90: 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d  ** assert( strcm
5ea0: 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65  p(sqlite3_source
5eb0: 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52  id(),SQLITE_SOUR
5ec0: 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20  CE_ID)==0 );.** 
5ed0: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
5ee0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
5ef0: 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49  n(),SQLITE_VERSI
5f00: 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70  ON)==0 );.** </p
5f10: 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
5f20: 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
5f30: 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20  lite3_version[] 
5f40: 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20  string constant 
5f50: 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78  contains the tex
5f60: 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52  t of [SQLITE_VER
5f70: 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20  SION].** macro. 
5f80: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69   ^The sqlite3_li
5f90: 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74  bversion() funct
5fa0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ion returns a po
5fb0: 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20  inter to the.** 
5fc0: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  to the sqlite3_v
5fd0: 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20  ersion[] string 
5fe0: 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73  constant.  The s
5ff0: 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f  qlite3_libversio
6000: 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  n().** function 
6010: 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20  is provided for 
6020: 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63  use in DLLs sinc
6030: 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61  e DLL users usua
6040: 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a  lly do not have.
6050: 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73  ** direct access
6060: 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74   to string const
6070: 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20  ants within the 
6080: 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  DLL.  ^The.** sq
6090: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
60a0: 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69  _number() functi
60b0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e  on returns an in
60c0: 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a  teger equal to.*
60d0: 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  * [SQLITE_VERSIO
60e0: 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65  N_NUMBER].  ^The
60f0: 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69   sqlite3_sourcei
6100: 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  d() function ret
6110: 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74  urns .** a point
6120: 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63  er to a string c
6130: 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61  onstant whose va
6140: 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  lue is the same 
6150: 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49  as the .** [SQLI
6160: 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20  TE_SOURCE_ID] C 
6170: 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  preprocessor mac
6180: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ro..**.** See al
6190: 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73  so: [sqlite_vers
61a0: 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
61b0: 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e  te_source_id()].
61c0: 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
61d0: 6f 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65  onst char sqlite
61e0: 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51  3_version[] = SQ
61f0: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51  LITE_VERSION;.SQ
6200: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
6210: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62  har *sqlite3_lib
6220: 76 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53  version(void);.S
6230: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
6240: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f  char *sqlite3_so
6250: 75 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51  urceid(void);.SQ
6260: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
6270: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
6280: 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f  number(void);../
6290: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
62a0: 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20  un-Time Library 
62b0: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69  Compilation Opti
62c0: 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a  ons Diagnostics.
62d0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
62e0: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
62f0: 5f 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e  _used() function
6300: 20 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20   returns 0 or 1 
6310: 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77  .** indicating w
6320: 68 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69  hether the speci
6330: 66 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20  fied option was 
6340: 64 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63  defined at .** c
6350: 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54  ompile time.  ^T
6360: 68 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69  he SQLITE_ prefi
6370: 78 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  x may be omitted
6380: 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70   from the .** op
6390: 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64  tion name passed
63a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70   to sqlite3_comp
63b0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
63c0: 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .  .**.** ^The s
63d0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
63e0: 74 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74  tion_get() funct
63f0: 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61  ion allows itera
6400: 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65  ting.** over the
6410: 20 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73   list of options
6420: 20 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e   that were defin
6430: 65 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  ed at compile ti
6440: 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69  me by.** returni
6450: 6e 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70  ng the N-th comp
6460: 69 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile time option 
6470: 73 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69  string.  ^If N i
6480: 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a  s out of range,.
6490: 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  ** sqlite3_compi
64a0: 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72  leoption_get() r
64b0: 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
64c0: 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c  inter.  ^The SQL
64d0: 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20  ITE_ .** prefix 
64e0: 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
64f0: 61 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75  any strings retu
6500: 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  rned by .** sqli
6510: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
6520: 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  n_get()..**.** ^
6530: 53 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20  Support for the 
6540: 64 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74  diagnostic funct
6550: 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d  ions sqlite3_com
6560: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
6570: 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33  ).** and sqlite3
6580: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6590: 65 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74  et() may be omit
65a0: 74 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e  ted by specifyin
65b0: 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  g the .** [SQLIT
65c0: 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50  E_OMIT_COMPILEOP
65d0: 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69  TION_DIAGS] opti
65e0: 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69  on at compile ti
65f0: 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  me..**.** See al
6600: 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  so: SQL function
6610: 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c  s [sqlite_compil
6620: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20  eoption_used()] 
6630: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63  and.** [sqlite_c
6640: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74  ompileoption_get
6650: 28 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d  ()] and the [com
6660: 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61  pile_options pra
6670: 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  gma]..*/.#ifndef
6680: 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d   SQLITE_OMIT_COM
6690: 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53  PILEOPTION_DIAGS
66a0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
66b0: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
66c0: 70 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74  ption_used(const
66d0: 20 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29   char *zOptName)
66e0: 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
66f0: 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
6700: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6710: 65 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69  et(int N);.#endi
6720: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
6730: 46 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49  F: Test To See I
6740: 66 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73  f The Library Is
6750: 20 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a   Threadsafe.**.*
6760: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
6770: 68 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63  hreadsafe() func
6780: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72  tion returns zer
6790: 6f 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  o if and only if
67a0: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63  .** SQLite was c
67b0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74  ompiled with mut
67c0: 65 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74  exing code omitt
67d0: 65 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a  ed due to the.**
67e0: 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
67f0: 41 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AFE] compile-tim
6800: 65 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73  e option being s
6810: 65 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53  et to 0..**.** S
6820: 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d  QLite can be com
6830: 70 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69  piled with or wi
6840: 74 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20  thout mutexes.  
6850: 57 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  When.** the [SQL
6860: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
6870: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
6880: 61 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20  acro is 1 or 2, 
6890: 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65  mutexes.** are e
68a0: 6e 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74  nabled and SQLit
68b0: 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e  e is threadsafe.
68c0: 20 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53    When the.** [S
68d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
68e0: 5d 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a  ] macro is 0, .*
68f0: 2a 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72  * the mutexes ar
6900: 65 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68  e omitted.  With
6910: 6f 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c  out the mutexes,
6920: 20 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a   it is not safe.
6930: 2a 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65  ** to use SQLite
6940: 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72   concurrently fr
6950: 6f 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  om more than one
6960: 20 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45   thread..**.** E
6970: 6e 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20  nabling mutexes 
6980: 69 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61  incurs a measura
6990: 62 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ble performance 
69a0: 70 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69  penalty..** So i
69b0: 66 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74  f speed is of ut
69c0: 6d 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c  most importance,
69d0: 20 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20   it makes sense 
69e0: 74 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68  to disable.** th
69f0: 65 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20  e mutexes.  But 
6a00: 66 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65  for maximum safe
6a10: 74 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75  ty, mutexes shou
6a20: 6c 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a  ld be enabled..*
6a30: 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
6a40: 65 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d  ehavior is for m
6a50: 75 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61  utexes to be ena
6a60: 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  bled..**.** This
6a70: 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62   interface can b
6a80: 65 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70  e used by an app
6a90: 6c 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65  lication to make
6aa0: 20 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a   sure that the.*
6ab0: 2a 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c  * version of SQL
6ac0: 69 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c  ite that it is l
6ad0: 69 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77  inking against w
6ae0: 61 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  as compiled with
6af0: 0a 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20  .** the desired 
6b00: 73 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b  setting of the [
6b10: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
6b20: 45 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20  E] macro..**.** 
6b30: 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f  This interface o
6b40: 6e 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74  nly reports on t
6b50: 68 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  he compile-time 
6b60: 6d 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a  mutex setting.**
6b70: 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   of the [SQLITE_
6b80: 54 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67  THREADSAFE] flag
6b90: 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20  .  If SQLite is 
6ba0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
6bb0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
6bc0: 46 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20  FE=1 or =2 then 
6bd0: 6d 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62  mutexes are enab
6be0: 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62  led by default b
6bf0: 75 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c  ut.** can be ful
6c00: 6c 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20  ly or partially 
6c10: 64 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61  disabled using a
6c20: 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
6c30: 33 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77  3_config()].** w
6c40: 69 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53  ith the verbs [S
6c50: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
6c60: 47 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c  GLETHREAD], [SQL
6c70: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
6c80: 54 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b  THREAD],.** or [
6c90: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
6ca0: 54 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74  TEX].  ^(The ret
6cb0: 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65  urn value of the
6cc0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65  .** sqlite3_thre
6cd0: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
6ce0: 6e 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65  n shows only the
6cf0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65   compile-time se
6d00: 74 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65  tting of.** thre
6d10: 61 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61  ad safety, not a
6d20: 6e 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e  ny run-time chan
6d30: 67 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74  ges to that sett
6d40: 69 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73  ing made by.** s
6d50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e  qlite3_config().
6d60: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
6d70: 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
6d80: 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74  e from sqlite3_t
6d90: 68 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69  hreadsafe().** i
6da0: 73 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63  s unchanged by c
6db0: 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
6dc0: 63 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a  config().)^.**.*
6dd0: 2a 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61  * See the [threa
6de0: 64 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d  ding mode] docum
6df0: 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64  entation for add
6e00: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
6e10: 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ion..*/.SQLITE_A
6e20: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  PI int sqlite3_t
6e30: 68 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b  hreadsafe(void);
6e40: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6e50: 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
6e60: 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20  ction Handle.** 
6e70: 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62  KEYWORDS: {datab
6e80: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20  ase connection} 
6e90: 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  {database connec
6ea0: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63  tions}.**.** Eac
6eb0: 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61  h open SQLite da
6ec0: 74 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73  tabase is repres
6ed0: 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74  ented by a point
6ee0: 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
6ef0: 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71  e of.** the opaq
6f00: 75 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d  ue structure nam
6f10: 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49  ed "sqlite3".  I
6f20: 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74  t is useful to t
6f30: 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74  hink of an sqlit
6f40: 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73  e3.** pointer as
6f50: 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65   an object.  The
6f60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
6f70: 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
6f80: 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  16()], and.** [s
6f90: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
6fa0: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ] interfaces are
6fb0: 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72   its constructor
6fc0: 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  s, and [sqlite3_
6fd0: 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69  close()].** is i
6fe0: 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e 20 20  ts destructor.  
6ff0: 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79 20 6f  There are many o
7000: 74 68 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  ther interfaces 
7010: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
7020: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
7030: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
7040: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
7050: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
7060: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
7070: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
7080: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
7090: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
70a0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
70b0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
70c0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
70d0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
70e0: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
70f0: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
7100: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
7110: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
7120: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
7130: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
7140: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
7150: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
7160: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
7170: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
7180: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
7190: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
71a0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
71b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
71c0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
71d0: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
71e0: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
71f0: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
7200: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
7210: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
7220: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
7230: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
7240: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
7250: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
7260: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
7270: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
7280: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
7290: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
72a0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
72b0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
72c0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
72d0: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
72e0: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
72f0: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
7300: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
7310: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
7320: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
7330: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
7340: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
7350: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
7360: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
7370: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
7380: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
7390: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
73a0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
73b0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
73c0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
73d0: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
73e0: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
73f0: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
7400: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
7410: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
7420: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
7430: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
7440: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
7450: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
7460: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
7470: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
7480: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
7490: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
74a0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
74b0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
74c0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
74d0: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
74e0: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
74f0: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
7500: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
7510: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
7520: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
7530: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
7540: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
7550: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
7560: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
7570: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
7580: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
7590: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
75a0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
75b0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
75c0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
75d0: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
75e0: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
75f0: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
7600: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72  qlite3_close() r
7610: 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20 64 65  outine is the de
7620: 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65  structor for the
7630: 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63   [sqlite3] objec
7640: 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  t..** ^Calls to 
7650: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20  sqlite3_close() 
7660: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
7670: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   if the [sqlite3
7680: 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73  ] object is.** s
7690: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
76a0: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
76b0: 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75 72 63  sociated resourc
76c0: 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74  es are deallocat
76d0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ed..**.** Applic
76e0: 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c  ations must [sql
76f0: 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20  ite3_finalize | 
7700: 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70  finalize] all [p
7710: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
7720: 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ts].** and [sqli
7730: 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c  te3_blob_close |
7740: 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f   close] all [BLO
7750: 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63  B handles] assoc
7760: 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  iated with.** th
7770: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
7780: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
7790: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
77a0: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
77b0: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
77c0: 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  e() is called on
77d0: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
77e0: 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74  nection] that st
77f0: 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74  ill has.** outst
7800: 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64  anding [prepared
7810: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20   statements] or 
7820: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
7830: 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 0a  then it returns.
7840: 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a  ** SQLITE_BUSY..
7850: 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74  **.** ^If [sqlit
7860: 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73 20 69  e3_close()] is i
7870: 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61 20 74  nvoked while a t
7880: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
7890: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
78a0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
78b0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
78c0: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
78d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
78e0: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
78f0: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
7900: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
7910: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
7920: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
7930: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
7940: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
7950: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
7960: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
7970: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
7980: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
7990: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
79a0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
79b0: 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68 20 61  3_close() with a
79c0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72   NULL pointer ar
79d0: 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20  gument is a .** 
79e0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a  harmless no-op..
79f0: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
7a00: 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  t sqlite3_close(
7a10: 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f 2a 0a  sqlite3 *);../*.
7a20: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
7a30: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
7a40: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
7a50: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
7a60: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
7a70: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
7a80: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
7a90: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
7aa0: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
7ab0: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
7ac0: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
7ad0: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
7ae0: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
7af0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
7b00: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
7b10: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
7b20: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
7b30: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
7b40: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
7b50: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
7b60: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
7b70: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
7b80: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
7b90: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
7ba0: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
7bb0: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
7bc0: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
7bd0: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
7be0: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
7bf0: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
7c00: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
7c10: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
7c20: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
7c30: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
7c40: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
7c50: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
7c60: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
7c70: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
7c80: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
7c90: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
7ca0: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
7cb0: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
7cc0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
7cd0: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
7ce0: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
7cf0: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
7d00: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
7d10: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
7d20: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
7d30: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
7d40: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
7d50: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
7d60: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
7d70: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
7d80: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
7d90: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
7da0: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
7db0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
7dc0: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
7dd0: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
7de0: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
7df0: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
7e00: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
7e10: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
7e20: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
7e30: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
7e40: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
7e50: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
7e60: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
7e70: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
7e80: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
7e90: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
7ea0: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
7eb0: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
7ec0: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
7ed0: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
7ee0: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
7ef0: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
7f00: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
7f10: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
7f20: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
7f30: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
7f40: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
7f50: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
7f60: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
7f70: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
7f80: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
7f90: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
7fa0: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
7fb0: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
7fc0: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
7fd0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
7fe0: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
7ff0: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
8000: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
8010: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
8020: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
8030: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
8040: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
8050: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
8060: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
8070: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
8080: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
8090: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
80a0: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
80b0: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
80c0: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
80d0: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
80e0: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
80f0: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
8100: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
8110: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
8120: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
8130: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
8140: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
8150: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
8160: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
8170: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
8180: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
8190: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
81a0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
81b0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
81c0: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
81d0: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
81e0: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
81f0: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
8200: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
8210: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
8220: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
8230: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
8240: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
8250: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
8260: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
8270: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
8280: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
8290: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
82a0: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
82b0: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
82c0: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
82d0: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
82e0: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
82f0: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
8300: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
8310: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
8320: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
8330: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
8340: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
8350: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
8360: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
8370: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
8380: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
8390: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
83a0: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
83b0: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
83c0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
83d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
83e0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
83f0: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
8400: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
8410: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
8420: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
8430: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
8440: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
8450: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
8460: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
8470: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
8480: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
8490: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
84a0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
84b0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
84c0: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
84d0: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
84e0: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
84f0: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
8500: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
8510: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
8520: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
8530: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
8540: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
8550: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
8560: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
8570: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
8580: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
8590: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
85a0: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
85b0: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
85c0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
85d0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
85e0: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
85f0: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
8600: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
8610: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
8620: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
8630: 6c 6f 73 65 20 5b 64 61 74 61 62 61 73 65 20 63  lose [database c
8640: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69  onnection] speci
8650: 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  fied by.**      
8660: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
8670: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
8680: 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65  c() while sqlite
8690: 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e  3_exec() is runn
86a0: 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ing..** <li> The
86b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
86c0: 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68 65  t not modify the
86d0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
86e0: 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  ext passed into.
86f0: 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64 20  **      the 2nd 
8700: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c  parameter of sql
8710: 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c  ite3_exec() whil
8720: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
8730: 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20   is running..** 
8740: 3c 2f 75 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  </ul>.*/.SQLITE_
8750: 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
8760: 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65 33 2a  exec(.  sqlite3*
8770: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
8780: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8790: 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
87a0: 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
87b0: 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20 20 20  t char *sql,    
87c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
87d0: 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f         /* SQL to
87e0: 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f   be evaluated */
87f0: 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62 61 63  .  int (*callbac
8800: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
8810: 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20 2f 2a  r**,char**),  /*
8820: 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   Callback functi
8830: 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 2c 20  on */.  void *, 
8840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8850: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8860: 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75 6d 65     /* 1st argume
8870: 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b 20 2a  nt to callback *
8880: 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72 6d 73  /.  char **errms
8890: 67 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  g               
88a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
88b0: 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74  * Error msg writ
88c0: 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a  ten here */.);..
88d0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
88e0: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
88f0: 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45  KEYWORDS: SQLITE
8900: 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64 65 7d  _OK {error code}
8910: 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a   {error codes}.*
8920: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72 65 73  * KEYWORDS: {res
8930: 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73 75 6c  ult code} {resul
8940: 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d  t codes}.**.** M
8950: 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63 74  any SQLite funct
8960: 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20 69  ions return an i
8970: 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63 6f  nteger result co
8980: 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74 20  de from the set 
8990: 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69 6e  shown.** here in
89a0: 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63 61   order to indica
89b0: 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66 61  te success or fa
89c0: 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  ilure..**.** New
89d0: 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61 79   error codes may
89e0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
89f0: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
8a00: 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  SQLite..**.** Se
8a10: 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54 45 5f  e also: [SQLITE_
8a20: 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65 78 74  IOERR_READ | ext
8a30: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
8a40: 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  es],.** [sqlite3
8a50: 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
8a60: 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52 4f 4c  t()] [SQLITE_ROL
8a70: 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74 20 63  LBACK | result c
8a80: 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  odes]..*/.#defin
8a90: 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20 20 20  e SQLITE_OK     
8aa0: 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53 75 63        0   /* Suc
8ab0: 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74 20 2a  cessful result *
8ac0: 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67 2d 6f  /./* beginning-o
8ad0: 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f  f-error-codes */
8ae0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8af0: 45 52 52 4f 52 20 20 20 20 20 20 20 20 31 20 20  ERROR        1  
8b00: 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20 6f 72   /* SQL error or
8b10: 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62 61 73   missing databas
8b20: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
8b30: 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20 20 20  ITE_INTERNAL    
8b40: 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e 61 6c   2   /* Internal
8b50: 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69 6e 20   logic error in 
8b60: 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66 69 6e  SQLite */.#defin
8b70: 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20 20 20  e SQLITE_PERM   
8b80: 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41 63 63        3   /* Acc
8b90: 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e 20 64  ess permission d
8ba0: 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  enied */.#define
8bb0: 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 20 20   SQLITE_ABORT   
8bc0: 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61 6c 6c       4   /* Call
8bd0: 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72 65 71  back routine req
8be0: 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72 74 20  uested an abort 
8bf0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
8c00: 45 5f 42 55 53 59 20 20 20 20 20 20 20 20 20 35  E_BUSY         5
8c10: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
8c20: 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63 6b 65  se file is locke
8c30: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
8c40: 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20 20 20  ITE_LOCKED      
8c50: 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c 65 20   6   /* A table 
8c60: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
8c70: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
8c80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  fine SQLITE_NOME
8c90: 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20  M        7   /* 
8ca0: 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 65  A malloc() faile
8cb0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
8cc0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  ITE_READONLY    
8cd0: 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70 74 20   8   /* Attempt 
8ce0: 74 6f 20 77 72 69 74 65 20 61 20 72 65 61 64 6f  to write a reado
8cf0: 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  nly database */.
8d00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
8d10: 4e 54 45 52 52 55 50 54 20 20 20 20 39 20 20 20  NTERRUPT    9   
8d20: 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74 65 72  /* Operation ter
8d30: 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c 69 74  minated by sqlit
8d40: 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2a 2f  e3_interrupt()*/
8d50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8d60: 49 4f 45 52 52 20 20 20 20 20 20 20 31 30 20 20  IOERR       10  
8d70: 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20 6f 66   /* Some kind of
8d80: 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f 72 20   disk I/O error 
8d90: 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64 65 66  occurred */.#def
8da0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 52 55  ine SQLITE_CORRU
8db0: 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54  PT     11   /* T
8dc0: 68 65 20 64 61 74 61 62 61 73 65 20 64 69 73 6b  he database disk
8dd0: 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66 6f 72   image is malfor
8de0: 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  med */.#define S
8df0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 20 20  QLITE_NOTFOUND  
8e00: 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77    12   /* Unknow
8e10: 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71 6c 69  n opcode in sqli
8e20: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
8e30: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
8e40: 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20 20 20  LITE_FULL       
8e50: 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72 74 69   13   /* Inserti
8e60: 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61 75 73  on failed becaus
8e70: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 66 75  e database is fu
8e80: 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ll */.#define SQ
8e90: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 20 20  LITE_CANTOPEN   
8ea0: 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c 65 20   14   /* Unable 
8eb0: 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61  to open the data
8ec0: 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65  base file */.#de
8ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 4f 54  fine SQLITE_PROT
8ee0: 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f 2a 20  OCOL    15   /* 
8ef0: 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20 70 72  Database lock pr
8f00: 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a  otocol error */.
8f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 45  #define SQLITE_E
8f20: 4d 50 54 59 20 20 20 20 20 20 20 31 36 20 20 20  MPTY       16   
8f30: 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73 20 65  /* Database is e
8f40: 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  mpty */.#define 
8f50: 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20 20 20  SQLITE_SCHEMA   
8f60: 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65 20 64     17   /* The d
8f70: 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
8f80: 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66 69 6e  hanged */.#defin
8f90: 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49 47 20  e SQLITE_TOOBIG 
8fa0: 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53 74 72       18   /* Str
8fb0: 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78 63 65  ing or BLOB exce
8fc0: 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74 20 2a  eds size limit *
8fd0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
8fe0: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31 39 20  _CONSTRAINT  19 
8ff0: 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65 20 74    /* Abort due t
9000: 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  o constraint vio
9010: 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e  lation */.#defin
9020: 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41 54 43  e SQLITE_MISMATC
9030: 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44 61 74  H    20   /* Dat
9040: 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63 68 20  a type mismatch 
9050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9060: 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20 32 31  E_MISUSE      21
9070: 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20 75 73     /* Library us
9080: 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 2a  ed incorrectly *
9090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
90a0: 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32 32 20  _NOLFS       22 
90b0: 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66 65 61    /* Uses OS fea
90c0: 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70 6f 72  tures not suppor
90d0: 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23  ted on host */.#
90e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 55  define SQLITE_AU
90f0: 54 48 20 20 20 20 20 20 20 20 32 33 20 20 20 2f  TH        23   /
9100: 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20  * Authorization 
9110: 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69 6e  denied */.#defin
9120: 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41 54 20  e SQLITE_FORMAT 
9130: 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41 75 78       24   /* Aux
9140: 69 6c 69 61 72 79 20 64 61 74 61 62 61 73 65 20  iliary database 
9150: 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a 2f 0a  format error */.
9160: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
9170: 41 4e 47 45 20 20 20 20 20 20 20 32 35 20 20 20  ANGE       25   
9180: 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  /* 2nd parameter
9190: 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
91a0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 2a 2f   out of range */
91b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
91c0: 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36 20 20  NOTADB      26  
91d0: 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65 64 20   /* File opened 
91e0: 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20 64 61  that is not a da
91f0: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
9200: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f  define SQLITE_RO
9210: 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20 2f  W         100  /
9220: 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
9230: 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77   has another row
9240: 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e   ready */.#defin
9250: 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20  e SQLITE_DONE   
9260: 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c       101  /* sql
9270: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
9280: 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69  finished executi
9290: 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d  ng */./* end-of-
92a0: 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a  error-codes */..
92b0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
92c0: 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
92d0: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
92e0: 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 65 72 72  S: {extended err
92f0: 6f 72 20 63 6f 64 65 7d 20 7b 65 78 74 65 6e 64  or code} {extend
9300: 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 7d 0a  ed error codes}.
9310: 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78  ** KEYWORDS: {ex
9320: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
9330: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 72 65  de} {extended re
9340: 73 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a  sult codes}.**.*
9350: 2a 20 49 6e 20 69 74 73 20 64 65 66 61 75 6c 74  * In its default
9360: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20   configuration, 
9370: 53 51 4c 69 74 65 20 41 50 49 20 72 6f 75 74 69  SQLite API routi
9380: 6e 65 73 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  nes return one o
9390: 66 20 32 36 20 69 6e 74 65 67 65 72 0a 2a 2a 20  f 26 integer.** 
93a0: 5b 53 51 4c 49 54 45 5f 4f 4b 20 7c 20 72 65 73  [SQLITE_OK | res
93b0: 75 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77  ult codes].  How
93c0: 65 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65  ever, experience
93d0: 20 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20   has shown that 
93e0: 6d 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65  many of.** these
93f0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
9400: 65 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61  e too coarse-gra
9410: 69 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e  ined.  They do n
9420: 6f 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a  ot provide as.**
9430: 20 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f   much informatio
9440: 6e 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73  n about problems
9450: 20 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20   as programmers 
9460: 6d 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20  might like.  In 
9470: 61 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20  an effort to.** 
9480: 61 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65  address this, ne
9490: 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
94a0: 53 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20  SQLite (version 
94b0: 33 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29  3.3.8 and later)
94c0: 20 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70   include.** supp
94d0: 6f 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ort for addition
94e0: 61 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  al result codes 
94f0: 74 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72  that provide mor
9500: 65 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72  e detailed infor
9510: 6d 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20  mation.** about 
9520: 65 72 72 6f 72 73 2e 20 54 68 65 20 65 78 74 65  errors. The exte
9530: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
9540: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72  s are enabled or
9550: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20   disabled.** on 
9560: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63  a per database c
9570: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20  onnection basis 
9580: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
9590: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
95a0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41  esult_codes()] A
95b0: 50 49 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f  PI..**.** Some o
95c0: 66 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  f the available 
95d0: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
95e0: 63 6f 64 65 73 20 61 72 65 20 6c 69 73 74 65 64  codes are listed
95f0: 20 68 65 72 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61   here..** One ma
9600: 79 20 65 78 70 65 63 74 20 74 68 65 20 6e 75 6d  y expect the num
9610: 62 65 72 20 6f 66 20 65 78 74 65 6e 64 65 64 20  ber of extended 
9620: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 77 69 6c  result codes wil
9630: 6c 20 62 65 20 65 78 70 61 6e 64 0a 2a 2a 20 6f  l be expand.** o
9640: 76 65 72 20 74 69 6d 65 2e 20 20 53 6f 66 74 77  ver time.  Softw
9650: 61 72 65 20 74 68 61 74 20 75 73 65 73 20 65 78  are that uses ex
9660: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
9670: 64 65 73 20 73 68 6f 75 6c 64 20 65 78 70 65 63  des should expec
9680: 74 0a 2a 2a 20 74 6f 20 73 65 65 20 6e 65 77 20  t.** to see new 
9690: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 69 6e 20  result codes in 
96a0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
96b0: 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a  of SQLite..**.**
96c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 4f 4b 20 72   The SQLITE_OK r
96d0: 65 73 75 6c 74 20 63 6f 64 65 20 77 69 6c 6c 20  esult code will 
96e0: 6e 65 76 65 72 20 62 65 20 65 78 74 65 6e 64 65  never be extende
96f0: 64 2e 20 20 49 74 20 77 69 6c 6c 20 61 6c 77 61  d.  It will alwa
9700: 79 73 0a 2a 2a 20 62 65 20 65 78 61 63 74 6c 79  ys.** be exactly
9710: 20 7a 65 72 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e   zero..*/.#defin
9720: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
9730: 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
9740: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
9750: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
9760: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
9770: 4f 52 54 5f 52 45 41 44 20 20 20 20 20 20 20 20  ORT_READ        
9780: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9790: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
97a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 57 52 49  SQLITE_IOERR_WRI
97b0: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  TE             (
97c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
97d0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
97e0: 51 4c 49 54 45 5f 49 4f 45 52 52 5f 46 53 59 4e  QLITE_IOERR_FSYN
97f0: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53  C             (S
9800: 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 34  QLITE_IOERR | (4
9810: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
9820: 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52 5f 46  LITE_IOERR_DIR_F
9830: 53 59 4e 43 20 20 20 20 20 20 20 20 20 28 53 51  SYNC         (SQ
9840: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 35 3c  LITE_IOERR | (5<
9850: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9860: 49 54 45 5f 49 4f 45 52 52 5f 54 52 55 4e 43 41  ITE_IOERR_TRUNCA
9870: 54 45 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  TE          (SQL
9880: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 36 3c 3c  ITE_IOERR | (6<<
9890: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
98a0: 54 45 5f 49 4f 45 52 52 5f 46 53 54 41 54 20 20  TE_IOERR_FSTAT  
98b0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
98c0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 37 3c 3c 38  TE_IOERR | (7<<8
98d0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
98e0: 45 5f 49 4f 45 52 52 5f 55 4e 4c 4f 43 4b 20 20  E_IOERR_UNLOCK  
98f0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9900: 45 5f 49 4f 45 52 52 20 7c 20 28 38 3c 3c 38 29  E_IOERR | (8<<8)
9910: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
9920: 5f 49 4f 45 52 52 5f 52 44 4c 4f 43 4b 20 20 20  _IOERR_RDLOCK   
9930: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
9940: 5f 49 4f 45 52 52 20 7c 20 28 39 3c 3c 38 29 29  _IOERR | (9<<8))
9950: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9960: 49 4f 45 52 52 5f 44 45 4c 45 54 45 20 20 20 20  IOERR_DELETE    
9970: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9980: 49 4f 45 52 52 20 7c 20 28 31 30 3c 3c 38 29 29  IOERR | (10<<8))
9990: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
99a0: 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 20 20 20  IOERR_BLOCKED   
99b0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
99c0: 49 4f 45 52 52 20 7c 20 28 31 31 3c 3c 38 29 29  IOERR | (11<<8))
99d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
99e0: 49 4f 45 52 52 5f 4e 4f 4d 45 4d 20 20 20 20 20  IOERR_NOMEM     
99f0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9a00: 49 4f 45 52 52 20 7c 20 28 31 32 3c 3c 38 29 29  IOERR | (12<<8))
9a10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9a20: 49 4f 45 52 52 5f 41 43 43 45 53 53 20 20 20 20  IOERR_ACCESS    
9a30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9a40: 49 4f 45 52 52 20 7c 20 28 31 33 3c 3c 38 29 29  IOERR | (13<<8))
9a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9a60: 49 4f 45 52 52 5f 43 48 45 43 4b 52 45 53 45 52  IOERR_CHECKRESER
9a70: 56 45 44 4c 4f 43 4b 20 28 53 51 4c 49 54 45 5f  VEDLOCK (SQLITE_
9a80: 49 4f 45 52 52 20 7c 20 28 31 34 3c 3c 38 29 29  IOERR | (14<<8))
9a90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9aa0: 49 4f 45 52 52 5f 4c 4f 43 4b 20 20 20 20 20 20  IOERR_LOCK      
9ab0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9ac0: 49 4f 45 52 52 20 7c 20 28 31 35 3c 3c 38 29 29  IOERR | (15<<8))
9ad0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9ae0: 49 4f 45 52 52 5f 43 4c 4f 53 45 20 20 20 20 20  IOERR_CLOSE     
9af0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9b00: 49 4f 45 52 52 20 7c 20 28 31 36 3c 3c 38 29 29  IOERR | (16<<8))
9b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9b20: 49 4f 45 52 52 5f 44 49 52 5f 43 4c 4f 53 45 20  IOERR_DIR_CLOSE 
9b30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9b40: 49 4f 45 52 52 20 7c 20 28 31 37 3c 3c 38 29 29  IOERR | (17<<8))
9b50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9b60: 49 4f 45 52 52 5f 53 48 4d 4f 50 45 4e 20 20 20  IOERR_SHMOPEN   
9b70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9b80: 49 4f 45 52 52 20 7c 20 28 31 38 3c 3c 38 29 29  IOERR | (18<<8))
9b90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9ba0: 49 4f 45 52 52 5f 53 48 4d 53 49 5a 45 20 20 20  IOERR_SHMSIZE   
9bb0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9bc0: 49 4f 45 52 52 20 7c 20 28 31 39 3c 3c 38 29 29  IOERR | (19<<8))
9bd0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9be0: 49 4f 45 52 52 5f 53 48 4d 4c 4f 43 4b 20 20 20  IOERR_SHMLOCK   
9bf0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9c00: 49 4f 45 52 52 20 7c 20 28 32 30 3c 3c 38 29 29  IOERR | (20<<8))
9c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9c20: 49 4f 45 52 52 5f 53 48 4d 4d 41 50 20 20 20 20  IOERR_SHMMAP    
9c30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9c40: 49 4f 45 52 52 20 7c 20 28 32 31 3c 3c 38 29 29  IOERR | (21<<8))
9c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9c60: 49 4f 45 52 52 5f 53 45 45 4b 20 20 20 20 20 20  IOERR_SEEK      
9c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9c80: 49 4f 45 52 52 20 7c 20 28 32 32 3c 3c 38 29 29  IOERR | (22<<8))
9c90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9ca0: 4c 4f 43 4b 45 44 5f 53 48 41 52 45 44 43 41 43  LOCKED_SHAREDCAC
9cb0: 48 45 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  HE      (SQLITE_
9cc0: 4c 4f 43 4b 45 44 20 7c 20 20 28 31 3c 3c 38 29  LOCKED |  (1<<8)
9cd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
9ce0: 5f 42 55 53 59 5f 52 45 43 4f 56 45 52 59 20 20  _BUSY_RECOVERY  
9cf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
9d00: 5f 42 55 53 59 20 20 20 7c 20 20 28 31 3c 3c 38  _BUSY   |  (1<<8
9d10: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9d20: 45 5f 43 41 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d  E_CANTOPEN_NOTEM
9d30: 50 44 49 52 20 20 20 20 20 20 28 53 51 4c 49 54  PDIR      (SQLIT
9d40: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 31 3c  E_CANTOPEN | (1<
9d50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9d60: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 49 53 44  ITE_CANTOPEN_ISD
9d70: 49 52 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  IR          (SQL
9d80: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
9d90: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
9da0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
9db0: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
9dc0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
9dd0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
9de0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
9df0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
9e00: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
9e10: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
9e20: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
9e30: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
9e40: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
9e50: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
9e60: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
9e70: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
9e80: 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54     (SQLITE_ABORT
9e90: 20 7c 20 28 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a   | (2<<8))../*.*
9ea0: 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67  * CAPI3REF: Flag
9eb0: 73 20 46 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20  s For File Open 
9ec0: 4f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Operations.**.**
9ed0: 20 54 68 65 73 65 20 62 69 74 20 76 61 6c 75 65   These bit value
9ee0: 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66  s are intended f
9ef0: 6f 72 20 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a  or use in the.**
9f00: 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
9f10: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f  o the [sqlite3_o
9f20: 70 65 6e 5f 76 32 28 29 5d 20 69 6e 74 65 72 66  pen_v2()] interf
9f30: 61 63 65 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68  ace and.** in th
9f40: 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
9f50: 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
9f60: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
9f70: 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  d..*/.#define SQ
9f80: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
9f90: 4c 59 20 20 20 20 20 20 20 20 20 30 78 30 30 30  LY         0x000
9fa0: 30 30 30 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72  00001  /* Ok for
9fb0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
9fc0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
9fd0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
9fe0: 49 54 45 20 20 20 20 20 20 20 20 30 78 30 30 30  ITE        0x000
9ff0: 30 30 30 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72  00002  /* Ok for
a000: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
a010: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
a020: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
a030: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
a040: 30 30 30 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72  00004  /* Ok for
a050: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
a060: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
a070: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
a080: 4f 4e 43 4c 4f 53 45 20 20 20 20 30 78 30 30 30  ONCLOSE    0x000
a090: 30 30 30 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e  00008  /* VFS on
a0a0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
a0b0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
a0c0: 49 56 45 20 20 20 20 20 20 20 20 30 78 30 30 30  IVE        0x000
a0d0: 30 30 30 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00010  /* VFS on
a0e0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
a0f0: 4c 49 54 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52  LITE_OPEN_AUTOPR
a100: 4f 58 59 20 20 20 20 20 20 20 20 30 78 30 30 30  OXY        0x000
a110: 30 30 30 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00020  /* VFS on
a120: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
a130: 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20  LITE_OPEN_URI   
a140: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
a150: 30 30 30 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  00040  /* Ok for
a160: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
a170: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
a180: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44  LITE_OPEN_MAIN_D
a190: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
a1a0: 30 30 31 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00100  /* VFS on
a1b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
a1c0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44  LITE_OPEN_TEMP_D
a1d0: 42 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  B          0x000
a1e0: 30 30 32 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00200  /* VFS on
a1f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
a200: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
a210: 45 4e 54 5f 44 42 20 20 20 20 20 30 78 30 30 30  ENT_DB     0x000
a220: 30 30 34 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00400  /* VFS on
a230: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
a240: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a  LITE_OPEN_MAIN_J
a250: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
a260: 30 30 38 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  00800  /* VFS on
a270: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
a280: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
a290: 4f 55 52 4e 41 4c 20 20 20 20 20 30 78 30 30 30  OURNAL     0x000
a2a0: 30 31 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  01000  /* VFS on
a2b0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
a2c0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55  LITE_OPEN_SUBJOU
a2d0: 52 4e 41 4c 20 20 20 20 20 20 20 30 78 30 30 30  RNAL       0x000
a2e0: 30 32 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  02000  /* VFS on
a2f0: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
a300: 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52  LITE_OPEN_MASTER
a310: 5f 4a 4f 55 52 4e 41 4c 20 20 20 30 78 30 30 30  _JOURNAL   0x000
a320: 30 34 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  04000  /* VFS on
a330: 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
a340: 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
a350: 58 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  X          0x000
a360: 30 38 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  08000  /* Ok for
a370: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
a380: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
a390: 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55  LITE_OPEN_FULLMU
a3a0: 54 45 58 20 20 20 20 20 20 20 20 30 78 30 30 30  TEX        0x000
a3b0: 31 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  10000  /* Ok for
a3c0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
a3d0: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
a3e0: 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
a3f0: 43 41 43 48 45 20 20 20 20 20 20 30 78 30 30 30  CACHE      0x000
a400: 32 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  20000  /* Ok for
a410: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
a420: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
a430: 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
a440: 45 43 41 43 48 45 20 20 20 20 20 30 78 30 30 30  ECACHE     0x000
a450: 34 30 30 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72  40000  /* Ok for
a460: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
a470: 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  () */.#define SQ
a480: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20  LITE_OPEN_WAL   
a490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
a4a0: 38 30 30 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e  80000  /* VFS on
a4b0: 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76  ly */../* Reserv
a4c0: 65 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20  ed:             
a4d0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
a4e0: 46 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  F00000 */../*.**
a4f0: 20 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63   CAPI3REF: Devic
a500: 65 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63  e Characteristic
a510: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76  s.**.** The xDev
a520: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
a530: 63 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  cs method of the
a540: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a550: 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20  hods].** object 
a560: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
a570: 65 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65  er which is a ve
a580: 63 74 6f 72 20 6f 66 20 74 68 65 20 74 68 65 73  ctor of the thes
a590: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20  e.** bit values 
a5a0: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63  expressing I/O c
a5b0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f  haracteristics o
a5c0: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61  f the mass stora
a5d0: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  ge.** device tha
a5e0: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65  t holds the file
a5f0: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
a600: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
a610: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a  * refers to..**.
a620: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
a630: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
a640: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
a650: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
a660: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
a670: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
a680: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
a690: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
a6a0: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
a6b0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
a6c0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
a6d0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
a6e0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
a6f0: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
a700: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
a710: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
a720: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
a730: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
a740: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
a750: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
a760: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
a770: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
a780: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
a790: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
a7a0: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
a7b0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
a7c0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
a7d0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
a7e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
a7f0: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
a800: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
a810: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
a820: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
a830: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
a840: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
a850: 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53  xWrite().  The S
a860: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
a870: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
a880: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
a890: 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62  hat.** after reb
a8a0: 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  oot following a 
a8b0: 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c  crash or power l
a8c0: 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79  oss, the only by
a8d0: 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65  tes in a.** file
a8e0: 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74   that were writt
a8f0: 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63  en at the applic
a900: 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68  ation level migh
a910: 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a  t have changed.*
a920: 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63  * and that adjac
a930: 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20  ent bytes, even 
a940: 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65  bytes within the
a950: 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65   same sector are
a960: 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74  .** guaranteed t
a970: 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a  o be unchanged..
a980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
a990: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
a9a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
a9b0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
a9c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
a9d0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
a9e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
a9f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
aa00: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
aa10: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
aa20: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
aa30: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
aa40: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
aa50: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
aa60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
aa70: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
aa80: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
aa90: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
aaa0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
aab0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
aac0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
aad0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
aae0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
aaf0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
ab00: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
ab10: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
ab20: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
ab30: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
ab40: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
ab50: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
ab60: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
ab70: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
ab80: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
ab90: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
aba0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
abb0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
abc0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
abd0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
abe0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
abf0: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
ac00: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
ac10: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
ac20: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
ac30: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
ac40: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f     0x00001000../
ac50: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
ac60: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
ac70: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
ac80: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
ac90: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
aca0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
acb0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
acc0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
acd0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
ace0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
acf0: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
ad00: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
ad10: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
ad20: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
ad30: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
ad40: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
ad50: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
ad60: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
ad70: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
ad80: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
ad90: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
ada0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
adb0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
adc0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
add0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
ade0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
adf0: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
ae00: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
ae10: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
ae20: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
ae30: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
ae40: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
ae50: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
ae60: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
ae70: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
ae80: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
ae90: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
aea0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
aeb0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
aec0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
aed0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
aee0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
aef0: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
af00: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
af10: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
af20: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
af30: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
af40: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
af50: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
af60: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
af70: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
af80: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
af90: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
afa0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
afb0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
afc0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
afd0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
afe0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
aff0: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
b000: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
b010: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
b020: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
b030: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
b040: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
b050: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
b060: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
b070: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
b080: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
b090: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
b0a0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
b0b0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
b0c0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
b0d0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
b0e0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
b0f0: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
b100: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
b110: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
b120: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
b130: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
b140: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
b150: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
b160: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
b170: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
b180: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
b190: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
b1a0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
b1b0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
b1c0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
b1d0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
b1e0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
b1f0: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
b200: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
b210: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
b220: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
b230: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
b240: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
b250: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
b260: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
b270: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
b280: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
b290: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
b2a0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
b2b0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
b2c0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
b2d0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
b2e0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
b2f0: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
b300: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
b310: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
b320: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
b330: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
b340: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
b350: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
b360: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
b370: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
b380: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
b390: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
b3a0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
b3b0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
b3c0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
b3d0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
b3e0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
b3f0: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
b400: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
b410: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
b420: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
b430: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
b440: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
b450: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
b460: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
b470: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
b480: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
b490: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
b4a0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
b4b0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
b4c0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
b4d0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
b4e0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
b4f0: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
b500: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
b510: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
b520: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
b530: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
b540: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
b550: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
b560: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
b570: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
b580: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
b590: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
b5a0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
b5b0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
b5c0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
b5d0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
b5e0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
b5f0: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
b600: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
b610: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
b620: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
b630: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
b640: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
b650: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
b660: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
b670: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
b680: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
b690: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
b6a0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
b6b0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
b6c0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
b6d0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
b6e0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
b6f0: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
b700: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
b710: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
b720: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
b730: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
b740: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
b750: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
b760: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
b770: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
b780: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
b790: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
b7a0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
b7b0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
b7c0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
b7d0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
b7e0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
b7f0: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
b800: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
b810: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
b820: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
b830: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
b840: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
b850: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
b860: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
b870: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
b880: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
b890: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
b8a0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
b8b0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
b8c0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
b8d0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
b8e0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
b8f0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
b900: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
b910: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
b920: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
b930: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
b940: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
b950: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
b960: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
b970: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
b980: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
b990: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
b9a0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
b9b0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
b9c0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
b9d0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
b9e0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
b9f0: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
ba00: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
ba10: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
ba20: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
ba30: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
ba40: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
ba50: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
ba60: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
ba70: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
ba80: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
ba90: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
baa0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
bab0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
bac0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
bad0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
bae0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
baf0: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
bb00: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
bb10: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
bb20: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
bb30: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
bb40: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
bb50: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
bb60: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
bb70: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
bb80: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
bb90: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
bba0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
bbb0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
bbc0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
bbd0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
bbe0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
bbf0: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
bc00: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
bc10: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
bc20: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
bc30: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
bc40: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
bc50: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
bc60: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
bc70: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
bc80: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
bc90: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
bca0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
bcb0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
bcc0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
bcd0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
bce0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
bcf0: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
bd00: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
bd10: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
bd20: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
bd30: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
bd40: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
bd50: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
bd60: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
bd70: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
bd80: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
bd90: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
bda0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
bdb0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
bdc0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
bdd0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
bde0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
bdf0: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
be00: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
be10: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
be20: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
be30: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
be40: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
be50: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
be60: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
be70: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
be80: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
be90: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
bea0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
beb0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
bec0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
bed0: 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f  e..** A [SQLITE_
bee0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
bef0: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65  | list of opcode
bf00: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  s] less than 100
bf10: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
bf20: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
bf30: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73  hat define a cus
bf40: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  tom xFileControl
bf50: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75   method should u
bf60: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72  se opcodes.** gr
bf70: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74  eater than 100 t
bf80: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74  o avoid conflict
bf90: 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  s.  VFS implemen
bfa0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a  tations should.*
bfb0: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
bfc0: 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66  _NOTFOUND] for f
bfd0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
bfe0: 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f  des that they do
bff0: 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a   not.** recogniz
c000: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  e..**.** The xSe
c010: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
c020: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
c030: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
c040: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
c050: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
c060: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
c070: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
c080: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
c090: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
c0a0: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
c0b0: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
c0c0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
c0d0: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
c0e0: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
c0f0: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
c100: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
c110: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
c120: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
c130: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
c140: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
c150: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
c160: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69  P_ATOMIC].** <li
c170: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
c180: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c  ATOMIC512].** <l
c190: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
c1a0: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC1K].** <l
c1b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
c1c0: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC2K].** <l
c1d0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
c1e0: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC4K].** <l
c1f0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
c200: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC8K].** <l
c210: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
c220: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c  _ATOMIC16K].** <
c230: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
c240: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20  P_ATOMIC32K].** 
c250: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
c260: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a  AP_ATOMIC64K].**
c270: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
c280: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d  CAP_SAFE_APPEND]
c290: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c2a0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
c2b0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  L].** </ul>.**.*
c2c0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
c2d0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
c2e0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
c2f0: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
c300: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
c310: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
c320: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
c330: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
c340: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
c350: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
c360: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
c370: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
c380: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
c390: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
c3a0: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
c3b0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
c3c0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
c3d0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
c3e0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
c3f0: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
c400: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
c410: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
c420: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
c430: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
c440: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
c450: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
c460: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
c470: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
c480: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
c490: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
c4a0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
c4b0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
c4c0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
c4d0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
c4e0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
c4f0: 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49  Write()..**.** I
c500: 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e  f xRead() return
c510: 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  s SQLITE_IOERR_S
c520: 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73  HORT_READ it mus
c530: 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69  t also fill.** i
c540: 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72  n the unread por
c550: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66  tions of the buf
c560: 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20  fer with zeros. 
c570: 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66   A VFS that.** f
c580: 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  ails to zero-fil
c590: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69  l short reads mi
c5a0: 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b  ght seem to work
c5b0: 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
c5c0: 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66  ailure to zero-f
c5d0: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
c5e0: 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20  will eventually 
c5f0: 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62  lead to.** datab
c600: 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  ase corruption..
c610: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
c620: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
c630: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
c640: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
c650: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
c660: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
c670: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
c680: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
c690: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
c6a0: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
c6b0: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
c6c0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
c6d0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
c6e0: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
c6f0: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
c700: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
c710: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
c720: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
c730: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
c740: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
c750: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
c760: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
c770: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
c780: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
c790: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
c7a0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
c7b0: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
c7c0: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
c7d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
c7e0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
c7f0: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
c800: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
c810: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
c820: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
c830: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
c840: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
c850: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
c860: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
c870: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
c880: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
c890: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
c8a0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
c8b0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
c8c0: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
c8d0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
c8e0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
c8f0: 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f  for version 1 */
c900: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70  .  int (*xShmMap
c910: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
c920: 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67   int iPg, int pg
c930: 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f  sz, int, void vo
c940: 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74  latile**);.  int
c950: 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c   (*xShmLock)(sql
c960: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
c970: 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69  offset, int n, i
c980: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69  nt flags);.  voi
c990: 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29  d (*xShmBarrier)
c9a0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
c9b0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d  .  int (*xShmUnm
c9c0: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
c9d0: 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61  *, int deleteFla
c9e0: 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  g);.  /* Methods
c9f0: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
ca00: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a   for version 2 *
ca10: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
ca20: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
ca30: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
ca40: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
ca50: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ca60: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
ca70: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
ca80: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
ca90: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
caa0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
cab0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
cac0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
cad0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
cae0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
caf0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
cb00: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
cb10: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
cb20: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
cb30: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
cb40: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
cb50: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
cb60: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
cb70: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
cb80: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
cb90: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
cba0: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
cbb0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
cbc0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
cbd0: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
cbe0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
cbf0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
cc00: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
cc10: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
cc20: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
cc30: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
cc40: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
cc50: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
cc60: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
cc70: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
cc80: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
cc90: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
cca0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
ccb0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
ccc0: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
ccd0: 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ined..** <ul>.**
cce0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ccf0: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a  NTL_SIZE_HINT]].
cd00: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
cd10: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
cd20: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
cd30: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
cd40: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
cd50: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
cd60: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
cd70: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
cd80: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
cd90: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
cda0: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
cdb0: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
cdc0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
cdd0: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
cde0: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
cdf0: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
ce00: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
ce10: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
ce20: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
ce30: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
ce40: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
ce50: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
ce60: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
ce70: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
ce80: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  aster..**.** <li
ce90: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
cea0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
ceb0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
cec0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
ced0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
cee0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
cef0: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
cf00: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
cf10: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
cf20: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
cf30: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
cf40: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
cf50: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
cf60: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
cf70: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
cf80: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
cf90: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
cfa0: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
cfb0: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
cfc0: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
cfd0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
cfe0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
cff0: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
d000: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
d010: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
d020: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
d030: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
d040: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
d050: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
d060: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
d070: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
d080: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
d090: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
d0a0: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
d0b0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
d0c0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
d0d0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
d0e0: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
d0f0: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
d100: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
d110: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
d120: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
d130: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
d140: 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20  ction.  See the 
d150: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
d160: 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e  ntrol()] documen
d170: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64  tation for.** ad
d180: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
d190: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
d1a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
d1b0: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
d1c0: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46   ^(The [SQLITE_F
d1d0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
d1e0: 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  D] opcode is gen
d1f0: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
d200: 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61  y by.** SQLite a
d210: 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56  nd sent to all V
d220: 46 53 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66  FSes in place of
d230: 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78   a call to the x
d240: 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77  Sync method.** w
d250: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
d260: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20   connection has 
d270: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
d280: 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e  ous] set to OFF.
d290: 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69  )^.** Some speci
d2a0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65  alized VFSes nee
d2b0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e  d this signal in
d2c0: 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74   order to operat
d2d0: 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77  e correctly.** w
d2e0: 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  hen [PRAGMA sync
d2f0: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
d300: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
d310: 5d 20 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f  ] is set, but mo
d320: 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20  st .** VFSes do 
d330: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
d340: 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20  gnal and should 
d350: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
d360: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20  this opcode..** 
d370: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
d380: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71  uld not call [sq
d390: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
d3a0: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a  ol()] with this.
d3b0: 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  ** opcode as doi
d3c0: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70  ng so may disrup
d3d0: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
d3e0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
d3f0: 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74  ed VFSes.** that
d400: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
d410: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
d420: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
d430: 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e  _AV_RETRY]].** ^
d440: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d450: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
d460: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
d470: 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75   to configure au
d480: 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79  tomatic.** retry
d490: 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65   counts and inte
d4a0: 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69  rvals for certai
d4b0: 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61  n disk I/O opera
d4c0: 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a  tions for the.**
d4d0: 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69   windows [VFS] i
d4e0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
d4f0: 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e  de robustness in
d500: 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   the presence of
d510: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
d520: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
d530: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
d540: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
d550: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
d560: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
d570: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61  ile delete opera
d580: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74  tions up to 10 t
d590: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c  imes, with a del
d5a0: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c  ay.** of 25 mill
d5b0: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
d5c0: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20  the first retry 
d5d0: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c  and with the del
d5e0: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a  ay increasing.**
d5f0: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61   by an additiona
d600: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  l 25 millisecond
d610: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73  s with each subs
d620: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54  equent retry.  T
d630: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c  his.** opcode al
d640: 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76  lows these two v
d650: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65  alues (10 retrie
d660: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65  s and 25 millise
d670: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a  conds of delay).
d680: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65  ** to be adjuste
d690: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61  d.  The values a
d6a0: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61  re changed for a
d6b0: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ll database conn
d6c0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69  ections.** withi
d6d0: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
d6e0: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  ss.  The argumen
d6f0: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
d700: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  o an array of tw
d710: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68  o.** integers wh
d720: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e  ere the first in
d730: 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20  teger i the new 
d740: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20  retry count and 
d750: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e  the second.** in
d760: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c  teger is the del
d770: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69  ay.  If either i
d780: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69  nteger is negati
d790: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74  ve, then the set
d7a0: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  ting.** is not c
d7b0: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65  hanged but inste
d7c0: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ad the prior val
d7d0: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69  ue of that setti
d7e0: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ng is written.**
d7f0: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20   into the array 
d800: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20  entry, allowing 
d810: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72  the current retr
d820: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65  y settings to be
d830: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64  .** interrogated
d840: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70  .  The zDbName p
d850: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f  arameter is igno
d860: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  red..**.** <li>[
d870: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
d880: 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e  RSIST_WAL]].** ^
d890: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d8a0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f  L_PERSIST_WAL] o
d8b0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
d8c0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
d8d0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
d8e0: 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 48 65  [WAL | Write AHe
d8f0: 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e  ad Log] setting.
d900: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
d910: 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77  e auxiliary.** w
d920: 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61  rite ahead log a
d930: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
d940: 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20   files used for 
d950: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
d960: 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d  rol.** are autom
d970: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
d980: 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74   when the latest
d990: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74   connection to t
d9a0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
d9b0: 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20  loses.  Setting 
d9c0: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
d9d0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65  ode causes those
d9e0: 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73   files to persis
d9f0: 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65  t after.** close
da00: 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68  .  Persisting th
da10: 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75  e files is usefu
da20: 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f  l when other pro
da30: 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e  cesses that do n
da40: 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65  ot.** have write
da50: 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74   permission on t
da60: 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e  he directory con
da70: 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61  taining the data
da80: 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a  base file want.*
da90: 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61  * to read the da
daa0: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20  tabase file, as 
dab0: 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72  the WAL and shar
dac0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
dad0: 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e  must exist.** in
dae0: 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64   order for the d
daf0: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
db00: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75  adable.  The fou
db10: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
db20: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
db30: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
db40: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
db50: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
db60: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
db70: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
db80: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
db90: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
dba0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
dbb0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a  le persistent.**
dbc0: 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74   WAL mode.  If t
dbd0: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
dbe0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
dbf0: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
dc00: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c  e current.** WAL
dc10: 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74   persistence set
dc20: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
dc30: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
dc40: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
dc50: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
dc60: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
dc70: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
dc80: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
dc90: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
dca0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
dcb0: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72   "powersafe-over
dcc0: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22  write" or "PSOW"
dcd0: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50   setting.  The P
dce0: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64  SOW setting.** d
dcf0: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53  etermines the [S
dd00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
dd10: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
dd20: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78   bit of the.** x
dd30: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
dd40: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54  stics methods. T
dd50: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
dd60: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
dd70: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
dd80: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
dd90: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
dda0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
ddb0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
ddc0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
ddd0: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  sable zero-damag
dde0: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  e mode or 1 to e
ddf0: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  nable zero-damag
de00: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74  e.** mode.  If t
de10: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
de20: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
de30: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
de40: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72  e current.** zer
de50: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65  o-damage mode se
de60: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
de70: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
de80: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
de90: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
dea0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  L_OVERWRITE] opc
deb0: 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ode is invoked b
dec0: 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f  y SQLite after o
ded0: 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74  pening.** a writ
dee0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  e transaction to
def0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20   indicate that, 
df00: 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c  unless it is rol
df10: 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d  led back for som
df20: 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65  e.** reason, the
df30: 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65   entire database
df40: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76   file will be ov
df50: 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
df60: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61   current .** tra
df70: 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69  nsaction. This i
df80: 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d  s used by VACUUM
df90: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
dfa0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
dfb0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a  FCNTL_VFSNAME]].
dfc0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
dfd0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f  FCNTL_VFSNAME] o
dfe0: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
dff0: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
e000: 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20  names of.** all 
e010: 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56  [VFSes] in the V
e020: 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e  FS stack.  The n
e030: 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20  ames are of all 
e040: 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68  VFS shims and th
e050: 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f  e.** final botto
e060: 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20  m-level VFS are 
e070: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
e080: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
e090: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
e0a0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65  alloc()] and the
e0b0: 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65   result is store
e0c0: 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76  d in the char* v
e0d0: 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20  ariable.** that 
e0e0: 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
e0f0: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
e100: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
e110: 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54   points to..** T
e120: 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73  he caller is res
e130: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65  ponsible for fre
e140: 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20  eing the memory 
e150: 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77  when done.  As w
e160: 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d  ith.** all file-
e170: 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c  control actions,
e180: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61   there is no gua
e190: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73  rantee that this
e1a0: 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a   will actually.*
e1b0: 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20  * do anything.  
e1c0: 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69  Callers should i
e1d0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68  nitialize the ch
e1e0: 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20  ar* variable to 
e1f0: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
e200: 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66  r in case this f
e210: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e  ile-control is n
e220: 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20  ot implemented. 
e230: 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   This file-contr
e240: 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65  ol.** is intende
e250: 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63  d for diagnostic
e260: 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a   use only..**.**
e270: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
e280: 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20  NTL_PRAGMA]].** 
e290: 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41  ^Whenever a [PRA
e2a0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  GMA] statement i
e2b0: 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51  s parsed, an [SQ
e2c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
e2d0: 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  A] .** file cont
e2e0: 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74  rol is sent to t
e2f0: 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33  he open [sqlite3
e300: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f  _file] object co
e310: 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74  rresponding.** t
e320: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
e330: 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65  ile to which the
e340: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
e350: 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61  t refers. ^The a
e360: 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
e370: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
e380: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
e390: 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79  trol is an array
e3a0: 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20   of.** pointers 
e3b0: 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72  to strings (char
e3c0: 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65  **) in which the
e3d0: 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20   second element 
e3e0: 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20  of the array.** 
e3f0: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
e400: 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68  he pragma and th
e410: 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20  e third element 
e420: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
e430: 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61  to the.** pragma
e440: 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
e450: 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72  pragma has no ar
e460: 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61  gument.  ^The ha
e470: 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20  ndler for an.** 
e480: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
e490: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
e4a0: 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c  ol can optionall
e4b0: 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74  y make the first
e4c0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74   element.** of t
e4d0: 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65  he char** argume
e4e0: 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  nt point to a st
e4f0: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72  ring obtained fr
e500: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  om [sqlite3_mpri
e510: 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65  ntf()].** or the
e520: 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20   equivalent and 
e530: 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c  that string will
e540: 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75   become the resu
e550: 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  lt of the pragma
e560: 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72   or.** the error
e570: 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20   message if the 
e580: 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49  pragma fails. ^I
e590: 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
e5a0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
e5b0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
e5c0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  rns [SQLITE_NOTF
e5d0: 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d  OUND], then norm
e5e0: 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20  al .** [PRAGMA] 
e5f0: 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69  processing conti
e600: 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b  nues.  ^If the [
e610: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
e620: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
e630: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
e640: 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74  LITE_OK], then t
e650: 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65  he parser assume
e660: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46  s that the.** VF
e670: 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68  S has handled th
e680: 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20  e PRAGMA itself 
e690: 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67  and the parser g
e6a0: 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70  enerates a no-op
e6b0: 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
e6c0: 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  tement.  ^If the
e6d0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
e6e0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
e6f0: 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  rol returns.** a
e700: 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f  ny result code o
e710: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
e720: 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45  E_OK] or [SQLITE
e730: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74  _NOTFOUND], that
e740: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74   means.** that t
e750: 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72  he VFS encounter
e760: 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c  ed an error whil
e770: 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b  e handling the [
e780: 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a  PRAGMA] and the.
e790: 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f  ** compilation o
e7a0: 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69  f the PRAGMA fai
e7b0: 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ls with an error
e7c0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
e7d0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
e7e0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63   file control oc
e7f0: 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69  curs at the begi
e800: 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20  nning of pragma 
e810: 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73  statement analys
e820: 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20  is and so.** it 
e830: 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72  is able to overr
e840: 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52  ide built-in [PR
e850: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73  AGMA] statements
e860: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64  ..** </ul>.*/.#d
e870: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
e880: 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20 20 20  TL_LOCKSTATE    
e890: 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65             1.#de
e8a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f  fine SQLITE_GET_
e8b0: 4c 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20  LOCKPROXYFILE   
e8c0: 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66            2.#def
e8d0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c  ine SQLITE_SET_L
e8e0: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
e8f0: 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69           3.#defi
e900: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
e910: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
e920: 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
e930: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  e SQLITE_FCNTL_S
e940: 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20 20 20  IZE_HINT        
e950: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
e960: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
e970: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 20  UNK_SIZE        
e980: 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
e990: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
e9a0: 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20 20 20  E_POINTER       
e9b0: 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53       7.#define S
e9c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
e9d0: 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20 20 20  _OMITTED        
e9e0: 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51      8.#define SQ
e9f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
ea00: 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20 20 20  _AV_RETRY       
ea10: 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c     9.#define SQL
ea20: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
ea30: 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20  T_WAL           
ea40: 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   10.#define SQLI
ea50: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
ea60: 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
ea70: 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  11.#define SQLIT
ea80: 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20  E_FCNTL_VFSNAME 
ea90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
eaa0: 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
eab0: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
eac0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 31 33  _OVERWRITE    13
ead0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
eae0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20 20 20  FCNTL_PRAGMA    
eaf0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 34 0a               14.
eb00: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
eb10: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
eb20: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
eb30: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
eb40: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
eb50: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
eb60: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
eb70: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
eb80: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
eb90: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
eba0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
ebb0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
ebc0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
ebd0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
ebe0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
ebf0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
ec00: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
ec10: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
ec20: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
ec30: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
ec40: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
ec50: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
ec60: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
ec70: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
ec80: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
ec90: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
eca0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
ecb0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
ecc0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
ecd0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
ece0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
ecf0: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
ed00: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
ed10: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
ed20: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
ed30: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
ed40: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
ed50: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
ed60: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
ed70: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
ed80: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
ed90: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
eda0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
edb0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
edc0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
edd0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
ede0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
edf0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
ee00: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
ee10: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
ee20: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
ee30: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
ee40: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
ee50: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
ee60: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
ee70: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
ee80: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
ee90: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
eea0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
eeb0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
eec0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
eed0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
eee0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
eef0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
ef00: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
ef10: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
ef20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
ef30: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
ef40: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
ef50: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
ef60: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
ef70: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
ef80: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
ef90: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
efa0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
efb0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
efc0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
efd0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
efe0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
eff0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
f000: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
f010: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
f020: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
f030: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
f040: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
f050: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
f060: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
f070: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
f080: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
f090: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
f0a0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
f0b0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
f0c0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
f0d0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
f0e0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
f0f0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
f100: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
f110: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
f120: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
f130: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
f140: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
f150: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
f160: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
f170: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
f180: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
f190: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
f1a0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
f1b0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
f1c0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
f1d0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
f1e0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
f1f0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
f200: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
f210: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
f220: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
f230: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
f240: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
f250: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
f260: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
f270: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
f280: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
f290: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
f2a0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
f2b0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
f2c0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
f2d0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
f2e0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
f2f0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
f300: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
f310: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
f320: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
f330: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
f340: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
f350: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
f360: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
f370: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
f380: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
f390: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
f3a0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
f3b0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
f3c0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
f3d0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
f3e0: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
f3f0: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
f400: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
f410: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
f420: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
f430: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
f440: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
f450: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
f460: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
f470: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
f480: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
f490: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
f4a0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
f4b0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
f4c0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
f4d0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
f4e0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
f4f0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
f500: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
f510: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
f520: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
f530: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
f540: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
f550: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
f560: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
f570: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
f580: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
f590: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
f5a0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
f5b0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
f5c0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
f5d0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
f5e0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
f5f0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
f600: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
f610: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
f620: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
f630: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
f640: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
f650: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
f660: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
f670: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
f680: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
f690: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
f6a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
f6b0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
f6c0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
f6d0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
f6e0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
f6f0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
f700: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
f710: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
f720: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
f730: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
f740: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
f750: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
f760: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
f770: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
f780: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
f790: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
f7a0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
f7b0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
f7c0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
f7d0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
f7e0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
f7f0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
f800: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
f810: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
f820: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
f830: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
f840: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
f850: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
f860: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
f870: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
f880: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
f890: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
f8a0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
f8b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
f8c0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
f8d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
f8e0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
f8f0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
f900: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
f910: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
f920: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
f930: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
f940: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
f950: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
f960: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
f970: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
f980: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
f990: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
f9a0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
f9b0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
f9c0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
f9d0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
f9e0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
f9f0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
fa00: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
fa10: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
fa20: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
fa30: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
fa40: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
fa50: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
fa60: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
fa70: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
fa80: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
fa90: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
faa0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
fab0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
fac0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
fad0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
fae0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
faf0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
fb00: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
fb10: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
fb20: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
fb30: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
fb40: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
fb50: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
fb60: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
fb70: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
fb80: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
fb90: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
fba0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
fbb0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
fbc0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
fbd0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
fbe0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
fbf0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
fc00: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
fc10: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
fc20: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
fc30: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
fc40: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
fc50: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
fc60: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
fc70: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
fc80: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
fc90: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
fca0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
fcb0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
fcc0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
fcd0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
fce0: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
fcf0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
fd00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
fd10: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
fd20: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
fd30: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
fd40: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
fd50: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
fd60: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
fd70: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
fd80: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
fd90: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
fda0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
fdb0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
fdc0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
fdd0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
fde0: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
fdf0: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
fe00: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
fe10: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
fe20: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
fe30: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
fe40: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
fe50: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
fe60: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
fe70: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
fe80: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
fe90: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
fea0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
feb0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
fec0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
fed0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
fee0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
fef0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
ff00: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
ff10: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
ff20: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
ff30: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
ff40: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
ff50: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
ff60: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
ff70: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
ff80: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
ff90: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
ffa0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
ffb0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
ffc0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
ffd0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
ffe0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
fff0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
10000 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
10010 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
10020 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
10030 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
10040 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
10050 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
10060 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
10070 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
10080 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
10090 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
100a0 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
100b0 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
100c0 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
100d0 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
100e0 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
100f0 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
10100 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
10110 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
10120 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
10130 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
10140 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
10150 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
10160 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
10170 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
10180 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
10190 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
101a0 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
101b0 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
101c0 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
101d0 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
101e0 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
101f0 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
10200 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
10210 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
10220 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
10230 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
10240 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
10250 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
10260 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
10270 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
10280 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
10290 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
102a0 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
102b0 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
102c0 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
102d0 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
102e0 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
102f0 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
10300 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
10310 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
10320 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
10330 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
10340 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
10350 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
10360 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
10370 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
10380 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
10390 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
103a0 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
103b0 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
103c0 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
103d0 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
103e0 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
103f0 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
10400 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
10410 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
10420 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
10430 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
10440 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
10450 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
10460 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
10470 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
10480 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
10490 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
104a0 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
104b0 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
104c0 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
104d0 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
104e0 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
104f0 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
10500 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
10510 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
10520 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
10530 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
10540 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
10550 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
10560 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
10570 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
10580 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
10590 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
105a0 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
105b0 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
105c0 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
105d0 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
105e0 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
105f0 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
10600 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
10610 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
10620 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
10630 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
10640 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
10650 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
10660 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
10670 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
10680 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
10690 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
106a0 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
106b0 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
106c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
106d0 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
106e0 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
106f0 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
10700 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
10710 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
10720 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
10730 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
10740 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
10750 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
10760 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
10770 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
10780 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
10790 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
107a0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
107b0 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
107c0 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
107d0 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
107e0 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
107f0 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
10800 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
10810 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
10820 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
10830 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
10840 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
10850 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
10860 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
10870 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
10880 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
10890 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
108a0 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
108b0 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
108c0 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
108d0 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
108e0 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
108f0 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
10900 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
10910 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
10920 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
10930 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
10940 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
10950 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
10960 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
10970 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
10980 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
10990 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
109a0 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
109b0 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
109c0 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
109d0 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
109e0 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
109f0 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
10a00 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
10a10 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
10a20 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
10a30 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
10a40 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
10a50 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
10a60 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
10a70 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
10a80 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
10a90 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
10aa0 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
10ab0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
10ac0 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
10ad0 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
10ae0 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
10af0 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
10b00 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
10b10 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
10b20 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
10b30 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
10b40 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
10b50 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
10b60 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
10b70 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
10b80 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
10b90 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
10ba0 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
10bb0 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
10bc0 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
10bd0 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
10be0 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
10bf0 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
10c00 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
10c10 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
10c20 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
10c30 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
10c40 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
10c50 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
10c60 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
10c70 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
10c80 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
10c90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
10ca0 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
10cb0 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
10cc0 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
10cd0 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
10ce0 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
10cf0 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
10d00 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
10d10 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
10d20 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
10d30 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
10d40 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
10d50 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
10d60 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
10d70 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
10d80 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
10d90 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
10da0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
10db0 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
10dc0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
10dd0 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
10de0 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
10df0 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
10e00 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
10e10 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
10e20 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
10e30 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
10e40 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
10e50 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
10e60 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
10e70 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
10e80 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
10e90 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
10ea0 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
10eb0 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
10ec0 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
10ed0 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
10ee0 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
10ef0 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
10f00 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
10f10 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
10f20 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
10f30 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
10f40 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
10f50 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
10f60 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
10f70 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
10f80 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
10f90 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
10fa0 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
10fb0 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
10fc0 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
10fd0 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
10fe0 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
10ff0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
11000 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
11010 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
11020 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
11030 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
11040 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
11050 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
11060 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
11070 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
11080 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
11090 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
110a0 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
110b0 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
110c0 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
110d0 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
110e0 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
110f0 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
11100 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
11110 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
11120 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
11130 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
11140 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
11150 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
11160 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
11170 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
11180 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
11190 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
111a0 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
111b0 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
111c0 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
111d0 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
111e0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
111f0 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
11200 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
11210 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
11220 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
11230 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
11240 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
11250 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
11260 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
11270 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
11280 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
11290 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
112a0 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
112b0 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
112c0 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
112d0 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
112e0 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
112f0 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
11300 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
11310 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
11320 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
11330 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
11340 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
11350 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
11360 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
11370 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
11380 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
11390 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
113a0 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
113b0 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
113c0 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
113d0 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
113e0 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
113f0 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
11400 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
11410 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
11420 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
11430 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
11440 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
11450 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
11460 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
11470 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
11480 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
11490 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
114a0 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
114b0 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
114c0 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
114d0 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
114e0 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
114f0 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
11500 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
11510 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
11520 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
11530 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
11540 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
11550 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
11560 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
11570 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
11580 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
11590 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
115a0 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
115b0 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
115c0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
115d0 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
115e0 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
115f0 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
11600 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
11610 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
11620 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
11630 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
11640 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
11650 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
11660 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
11670 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
11680 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
11690 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
116a0 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
116b0 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
116c0 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
116d0 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
116e0 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
116f0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
11700 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
11710 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
11720 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
11730 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
11740 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
11750 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
11760 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
11770 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
11780 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
11790 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
117a0 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
117b0 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
117c0 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
117d0 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
117e0 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
117f0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
11800 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
11810 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
11820 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
11830 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
11840 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
11850 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
11860 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
11870 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
11880 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
11890 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
118a0 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
118b0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
118c0 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
118d0 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
118e0 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
118f0 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
11900 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
11910 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
11920 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
11930 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
11940 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
11950 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
11960 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
11970 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
11980 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
11990 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
119a0 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
119b0 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
119c0 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
119d0 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
119e0 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
119f0 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
11a00 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
11a10 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
11a20 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
11a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
11a40 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
11a50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
11a60 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
11a70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11a80 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
11a90 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
11aa0 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
11ab0 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
11ac0 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
11ad0 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
11ae0 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
11af0 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
11b00 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
11b10 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
11b20 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
11b30 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
11b40 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
11b50 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
11b60 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
11b70 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
11b80 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
11b90 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
11ba0 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
11bb0 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
11bc0 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
11bd0 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
11be0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
11bf0 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
11c00 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
11c10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
11c20 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
11c30 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
11c40 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
11c50 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
11c60 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
11c70 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
11c80 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
11c90 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
11ca0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
11cb0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
11cc0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
11cd0 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
11ce0 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
11cf0 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
11d00 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
11d10 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
11d20 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
11d30 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
11d40 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
11d50 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
11d60 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
11d70 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
11d80 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
11d90 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
11da0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
11db0 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
11dc0 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
11dd0 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
11de0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11df0 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
11e00 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
11e10 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
11e20 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
11e30 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
11e40 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
11e50 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
11e60 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
11e70 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
11e80 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
11e90 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
11ea0 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
11eb0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
11ec0 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
11ed0 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
11ee0 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
11ef0 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
11f00 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
11f10 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
11f20 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
11f30 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
11f40 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
11f50 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
11f60 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11f70 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
11f80 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
11f90 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
11fa0 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
11fb0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
11fc0 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
11fd0 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
11fe0 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
11ff0 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
12000 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12010 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
12020 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
12030 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
12040 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
12050 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
12060 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
12070 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
12080 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
12090 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
120a0 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
120b0 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
120c0 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
120d0 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
120e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
120f0 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
12100 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
12110 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
12120 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
12130 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
12140 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
12150 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12160 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
12170 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
12180 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12190 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
121a0 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
121b0 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
121c0 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
121d0 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
121e0 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
121f0 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
12200 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12210 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
12220 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
12230 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
12240 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
12250 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
12260 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
12270 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
12280 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
12290 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
122a0 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
122b0 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
122c0 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
122d0 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
122e0 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
122f0 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
12300 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
12310 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
12320 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
12330 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
12340 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
12350 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
12360 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
12370 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
12380 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
12390 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
123a0 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
123b0 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
123c0 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
123d0 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
123e0 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
123f0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12400 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
12410 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
12420 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
12430 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
12440 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
12450 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
12460 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
12470 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
12480 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
12490 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
124a0 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
124b0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
124c0 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
124d0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
124e0 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
124f0 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
12500 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
12510 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
12520 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
12530 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
12540 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12550 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
12560 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
12570 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
12580 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
12590 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
125a0 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
125b0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
125c0 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
125d0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
125e0 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
125f0 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
12600 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
12610 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
12620 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
12630 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
12640 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
12650 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
12660 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
12670 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
12680 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
12690 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
126a0 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
126b0 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
126c0 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
126d0 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
126e0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
126f0 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
12700 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
12710 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
12720 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
12730 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
12740 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
12750 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
12760 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
12770 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
12780 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
12790 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
127a0 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
127b0 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
127c0 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
127d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
127e0 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
127f0 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
12800 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
12810 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
12820 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
12830 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
12840 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
12850 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
12860 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
12870 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
12880 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
12890 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
128a0 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
128b0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
128c0 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
128d0 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
128e0 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
128f0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
12900 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
12910 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
12920 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
12930 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
12940 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
12950 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
12960 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
12970 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
12980 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
12990 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
129a0 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
129b0 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
129c0 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
129d0 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
129e0 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
129f0 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
12a00 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
12a10 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
12a20 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
12a30 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
12a40 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
12a50 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
12a60 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
12a70 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
12a80 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
12a90 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
12aa0 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
12ab0 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
12ac0 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
12ad0 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
12ae0 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
12af0 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
12b00 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
12b10 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
12b20 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
12b30 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
12b40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
12b50 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
12b60 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
12b70 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
12b80 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
12b90 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
12ba0 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
12bb0 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
12bc0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
12bd0 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
12be0 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
12bf0 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
12c00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
12c10 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  t sqlite3_initia
12c20 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 53 51 4c 49  lize(void);.SQLI
12c30 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
12c40 65 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64  e3_shutdown(void
12c50 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
12c60 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  t sqlite3_os_ini
12c70 74 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  t(void);.SQLITE_
12c80 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
12c90 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
12ca0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
12cb0 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
12cc0 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
12cd0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
12ce0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
12cf0 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
12d00 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
12d10 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
12d20 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
12d30 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
12d40 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
12d50 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
12d60 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
12d70 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
12d80 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
12d90 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
12da0 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
12db0 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
12dc0 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
12dd0 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
12de0 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
12df0 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
12e00 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
12e10 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
12e20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
12e30 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
12e40 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
12e50 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
12e60 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
12e70 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
12e80 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
12e90 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
12ea0 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
12eb0 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
12ec0 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
12ed0 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
12ee0 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
12ef0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
12f00 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
12f10 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
12f20 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
12f30 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
12f40 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
12f50 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
12f60 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
12f70 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12f80 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
12f90 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
12fa0 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
12fb0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12fc0 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
12fd0 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
12fe0 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
12ff0 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
13000 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
13010 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
13020 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13030 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
13040 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
13050 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
13060 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
13070 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
13080 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
13090 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
130a0 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
130b0 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
130c0 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
130d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
130e0 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
130f0 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
13100 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
13110 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
13120 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
13130 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
13140 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
13150 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
13160 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
13170 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
13180 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
13190 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
131a0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
131b0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
131c0 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
131d0 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
131e0 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
131f0 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
13200 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
13210 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
13220 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
13230 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
13240 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
13250 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
13260 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69  sqlite3_config(i
13270 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a  nt, ...);../*.**
13280 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
13290 67 75 72 65 20 64 61 74 61 62 61 73 65 20 63 6f  gure database co
132a0 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  nnections.**.** 
132b0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63  The sqlite3_db_c
132c0 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63  onfig() interfac
132d0 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b  e is used to mak
132e0 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a  e configuration.
132f0 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20  ** changes to a 
13300 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
13310 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65  tion].  The inte
13320 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72  rface is similar
13330 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
13340 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74  config()] except
13350 20 74 68 61 74 20 74 68 65 20 63 68 61 6e 67 65   that the change
13360 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e  s apply to a sin
13370 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  gle.** [database
13380 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70   connection] (sp
13390 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 66  ecified in the f
133a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a  irst argument)..
133b0 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  **.** The second
133c0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
133d0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44  ite3_db_config(D
133e0 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a  ,V,...)  is the.
133f0 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ** [SQLITE_DBCON
13400 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20  FIG_LOOKASIDE | 
13410 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65  configuration ve
13420 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72  rb] - an integer
13430 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69   code .** that i
13440 6e 64 69 63 61 74 65 73 20 77 68 61 74 20 61 73  ndicates what as
13450 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74  pect of the [dat
13460 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13470 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69  ] is being confi
13480 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71  gured..** Subseq
13490 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76  uent arguments v
134a0 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  ary depending on
134b0 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
134c0 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e  on verb..**.** ^
134d0 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
134e0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  _db_config() ret
134f0 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
13500 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20   and only if.** 
13510 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73  the call is cons
13520 69 64 65 72 65 64 20 73 75 63 63 65 73 73 66 75  idered successfu
13530 6c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  l..*/.SQLITE_API
13540 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f   int sqlite3_db_
13550 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c  config(sqlite3*,
13560 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a   int op, ...);..
13570 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13580 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
13590 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a  n Routines.**.**
135a0 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
135b0 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  this object defi
135c0 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
135d0 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65  e between SQLite
135e0 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65  .** and low-leve
135f0 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
13600 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ion routines..**
13610 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
13620 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20  is used in only 
13630 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65  one place in the
13640 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
13650 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20  e..** A pointer 
13660 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
13670 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73  f this object is
13680 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f   the argument to
13690 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
136a0 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20  fig()] when the 
136b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
136c0 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49  tion is.** [SQLI
136d0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
136e0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
136f0 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20  FIG_GETMALLOC]. 
13700 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67   .** By creating
13710 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
13720 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61  this object.** a
13730 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f  nd passing it to
13740 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
13750 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
13760 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72  _MALLOC]).** dur
13770 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ing configuratio
13780 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  n, an applicatio
13790 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e  n can specify an
137a0 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20   alternative.** 
137b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
137c0 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20  n subsystem for 
137d0 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f  SQLite to use fo
137e0 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20  r all of its.** 
137f0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e  dynamic memory n
13800 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  eeds..**.** Note
13810 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d   that SQLite com
13820 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c 20  es with several 
13830 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79  [built-in memory
13840 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20   allocators].** 
13850 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63 74  that are perfect
13860 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72 20  ly adequate for 
13870 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67  the overwhelming
13880 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70   majority of app
13890 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64  lications.** and
138a0 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63   that this objec
138b0 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c  t is only useful
138c0 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72   to a tiny minor
138d0 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
138e0 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63  ons.** with spec
138f0 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61  ialized memory a
13900 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72  llocation requir
13910 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62  ements.  This ob
13920 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20  ject is.** also 
13930 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74  used during test
13940 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e  ing of SQLite in
13950 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69 66   order to specif
13960 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65  y an alternative
13970 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
13980 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61  ator that simula
13990 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f  tes memory out-o
139a0 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69  f-memory conditi
139b0 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20  ons in.** order 
139c0 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 53  to verify that S
139d0 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20 67  QLite recovers g
139e0 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73  racefully from s
139f0 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e  uch.** condition
13a00 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61  s..**.** The xMa
13a10 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20  lloc, xRealloc, 
13a20 61 6e 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64  and xFree method
13a30 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65  s must work like
13a40 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29   the.** malloc()
13a50 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20  , realloc() and 
13a60 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73  free() functions
13a70 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61   from the standa
13a80 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a  rd C library..**
13a90 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74   ^SQLite guarant
13aa0 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65 63  ees that the sec
13ab0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
13ac0 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61  ** xRealloc is a
13ad0 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72 65  lways a value re
13ae0 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f  turned by a prio
13af0 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64  r call to xRound
13b00 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20  up..**.** xSize 
13b10 73 68 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68  should return th
13b20 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
13b30 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   of a memory all
13b40 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69  ocation.** previ
13b50 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66  ously obtained f
13b60 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78  rom xMalloc or x
13b70 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c  Realloc.  The al
13b80 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20  located size.** 
13b90 69 73 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61  is always at lea
13ba0 73 74 20 61 73 20 62 69 67 20 61 73 20 74 68 65  st as big as the
13bb0 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 20   requested size 
13bc0 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
13bd0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f  r..**.** The xRo
13be0 75 6e 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74  undup method ret
13bf0 75 72 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20  urns what would 
13c00 62 65 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  be the allocated
13c10 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65   size of.** a me
13c20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
13c30 67 69 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c  given a particul
13c40 61 72 20 72 65 71 75 65 73 74 65 64 20 73 69 7a  ar requested siz
13c50 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a  e.  Most memory.
13c60 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f  ** allocators ro
13c70 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c  und up memory al
13c80 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61  locations at lea
13c90 73 74 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d  st to the next m
13ca0 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e  ultiple.** of 8.
13cb0 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72    Some allocator
13cc0 73 20 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20  s round up to a 
13cd0 6c 61 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20  larger multiple 
13ce0 6f 72 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66  or to a power of
13cf0 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d   2..** Every mem
13d00 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
13d10 65 71 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e  equest coming in
13d20 20 74 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65   through [sqlite
13d30 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f  3_malloc()].** o
13d40 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
13d50 6f 63 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c  oc()] first call
13d60 73 20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20  s xRoundup.  If 
13d70 78 52 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73  xRoundup returns
13d80 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75   0, .** that cau
13d90 73 65 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f  ses the correspo
13da0 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  nding memory all
13db0 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e  ocation to fail.
13dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74  .**.** The xInit
13dd0 20 6d 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69   method initiali
13de0 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  zes the memory a
13df0 6c 6c 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20  llocator.  (For 
13e00 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d  example,.** it m
13e10 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e  ight allocate an
13e20 79 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  y require mutexe
13e30 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20  s or initialize 
13e40 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a  internal data.**
13e50 20 73 74 72 75 63 74 75 72 65 73 2e 20 20 54 68   structures.  Th
13e60 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  e xShutdown meth
13e70 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69  od is invoked (i
13e80 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a  ndirectly) by.**
13e90 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
13ea0 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64  wn()] and should
13eb0 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20   deallocate any 
13ec0 72 65 73 6f 75 72 63 65 73 20 61 63 71 75 69 72  resources acquir
13ed0 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20  ed.** by xInit. 
13ee0 20 54 68 65 20 70 41 70 70 44 61 74 61 20 70 6f   The pAppData po
13ef0 69 6e 74 65 72 20 69 73 20 75 73 65 64 20 61 73  inter is used as
13f00 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
13f10 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20  ter to.** xInit 
13f20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a  and xShutdown..*
13f30 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64  *.** SQLite hold
13f40 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
13f50 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45  TEX_STATIC_MASTE
13f60 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74  R] mutex when it
13f70 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20   invokes.** the 
13f80 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f  xInit method, so
13f90 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
13fa0 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68  d need not be th
13fb0 72 65 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a  readsafe.  The.*
13fc0 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68  * xShutdown meth
13fd0 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65  od is only calle
13fe0 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
13ff0 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69  shutdown()] so i
14000 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65  t does.** not ne
14010 65 64 20 74 6f 20 62 65 20 74 68 72 65 61 64 73  ed to be threads
14020 61 66 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72  afe either.  For
14030 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f   all other metho
14040 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f  ds, SQLite.** ho
14050 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
14060 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d  MUTEX_STATIC_MEM
14070 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20  ] mutex as long 
14080 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  as the.** [SQLIT
14090 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
140a0 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  US] configuratio
140b0 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e  n option is turn
140c0 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20  ed on (which.** 
140d0 69 74 20 69 73 20 62 79 20 64 65 66 61 75 6c 74  it is by default
140e0 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74  ) and so the met
140f0 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74  hods are automat
14100 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65  ically serialize
14110 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69  d..** However, i
14120 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  f [SQLITE_CONFIG
14130 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64  _MEMSTATUS] is d
14140 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68  isabled, then th
14150 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f  e other.** metho
14160 64 73 20 6d 75 73 74 20 62 65 20 74 68 72 65 61  ds must be threa
14170 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61  dsafe or else ma
14180 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72  ke their own arr
14190 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a  angements for.**
141a0 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a   serialization..
141b0 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  **.** SQLite wil
141c0 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78  l never invoke x
141d0 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e  Init() more than
141e0 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e   once without an
141f0 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20   intervening.** 
14200 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77  call to xShutdow
14210 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  n()..*/.typedef 
14220 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
14230 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74  em_methods sqlit
14240 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a  e3_mem_methods;.
14250 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d  struct sqlite3_m
14260 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76  em_methods {.  v
14270 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28  oid *(*xMalloc)(
14280 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a  int);         /*
14290 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
142a0 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  on function */. 
142b0 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76   void (*xFree)(v
142c0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
142d0 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f 72 20  /* Free a prior 
142e0 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
142f0 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63  void *(*xRealloc
14300 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f  )(void*,int);  /
14310 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f  * Resize an allo
14320 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20  cation */.  int 
14330 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b  (*xSize)(void*);
14340 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65             /* Re
14350 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66  turn the size of
14360 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a   an allocation *
14370 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64  /.  int (*xRound
14380 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  up)(int);       
14390 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72     /* Round up r
143a0 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61  equest size to a
143b0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a  llocation size *
143c0 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29  /.  int (*xInit)
143d0 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
143e0 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65     /* Initialize
143f0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
14400 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
14410 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69  (*xShutdown)(voi
14420 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69  d*);      /* Dei
14430 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65  nitialize the me
14440 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a  mory allocator *
14450 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61  /.  void *pAppDa
14460 74 61 3b 20 20 20 20 20 20 20 20 20 20 20 20 20  ta;             
14470 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74     /* Argument t
14480 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53  o xInit() and xS
14490 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a  hutdown() */.};.
144a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
144b0 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f   Configuration O
144c0 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ptions.** KEYWOR
144d0 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61 74 69  DS: {configurati
144e0 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a  on option}.**.**
144f0 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
14500 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62   are the availab
14510 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69  le integer confi
14520 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
14530 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20   that.** can be 
14540 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66 69  passed as the fi
14550 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
14560 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
14570 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
14580 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66  ..**.** New conf
14590 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
145a0 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
145b0 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  n future release
145c0 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20  s of SQLite..** 
145d0 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75  Existing configu
145e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
145f0 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69  ight be disconti
14600 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69  nued.  Applicati
14610 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68  ons.** should ch
14620 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
14630 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ode from [sqlite
14640 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  3_config()] to m
14650 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
14660 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
14670 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
14680 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
14690 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
146a0 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
146b0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
146c0 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
146d0 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
146e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
146f0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
14700 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b  **.** <dl>.** [[
14710 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
14720 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c 64 74  NGLETHREAD]] <dt
14730 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
14740 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e  INGLETHREAD</dt>
14750 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
14760 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
14770 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
14780 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
14790 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
147a0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e  ing mode] to Sin
147b0 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49 6e 20  gle-thread.  In 
147c0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20  other words, it 
147d0 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20  disables.** all 
147e0 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70 75 74  mutexing and put
147f0 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20 61 20  s SQLite into a 
14800 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20 63 61  mode where it ca
14810 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a  n only be used.*
14820 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20 74 68  * by a single th
14830 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51 4c 69  read.   ^If SQLi
14840 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77  te is compiled w
14850 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  ith.** the [SQLI
14860 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20  TE_THREADSAFE | 
14870 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
14880 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  E=0] compile-tim
14890 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a  e option then.**
148a0 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   it is not possi
148b0 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ble to change th
148c0 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
148d0 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65 66 61  e] from its defa
148e0 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  ult.** value of 
148f0 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 61 6e  Single-thread an
14900 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d so [sqlite3_co
14910 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
14920 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urn .** [SQLITE_
14930 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
14940 20 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45   with the SQLITE
14950 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
14960 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  READ.** configur
14970 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
14980 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
14990 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
149a0 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
149b0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
149c0 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  READ</dt>.** <dd
149d0 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72  >There are no ar
149e0 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20  guments to this 
149f0 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f  option.  ^This o
14a00 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
14a10 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  * [threading mod
14a20 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65  e] to Multi-thre
14a30 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  ad.  In other wo
14a40 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73  rds, it disables
14a50 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20  .** mutexing on 
14a60 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
14a70 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
14a80 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
14a90 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61  bjects..** The a
14aa0 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 72 65  pplication is re
14ab0 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 73 65  sponsible for se
14ac0 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65 73 73  rializing access
14ad0 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65   to.** [database
14ae0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
14af0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
14b00 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74  ements].  But ot
14b10 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61  her mutexes.** a
14b20 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20 74 68  re enabled so th
14b30 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62  at SQLite will b
14b40 65 20 73 61 66 65 20 74 6f 20 75 73 65 20 69 6e  e safe to use in
14b50 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
14b60 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74  d.** environment
14b70 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74   as long as no t
14b80 77 6f 20 74 68 72 65 61 64 73 20 61 74 74 65 6d  wo threads attem
14b90 70 74 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  pt to use the sa
14ba0 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  me.** [database 
14bb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74  connection] at t
14bc0 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e  he same time.  ^
14bd0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
14be0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
14bf0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
14c00 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
14c10 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
14c20 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14c30 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
14c40 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
14c50 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68 72 65  t the Multi-thre
14c60 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ad [threading mo
14c70 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
14c80 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
14c90 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
14ca0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
14cb0 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
14cc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
14cd0 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69 67 75  TITHREAD configu
14ce0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
14cf0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14d00 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
14d10 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  IZED]] <dt>SQLIT
14d20 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
14d30 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
14d40 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
14d50 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
14d60 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
14d70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
14d80 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
14d90 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
14da0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
14db0 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
14dc0 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
14dd0 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
14de0 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
14df0 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
14e00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
14e10 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
14e20 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
14e30 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
14e40 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
14e50 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
14e60 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
14e70 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
14e80 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
14e90 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
14ea0 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
14eb0 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
14ec0 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
14ed0 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
14ee0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
14ef0 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
14f00 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
14f10 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
14f20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
14f30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
14f40 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
14f50 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
14f60 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
14f70 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
14f80 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
14f90 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14fa0 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
14fb0 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
14fc0 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
14fd0 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
14fe0 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
14ff0 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
15000 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
15010 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
15020 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
15030 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
15040 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
15050 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
15060 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
15070 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
15080 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
15090 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
150a0 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
150b0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
150c0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64  NFIG_MALLOC]] <d
150d0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
150e0 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c  MALLOC</dt>.** <
150f0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
15100 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
15110 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
15120 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
15130 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
15140 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
15150 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  em_methods] stru
15160 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
15170 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
15180 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
15190 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61  w-level memory a
151a0 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
151b0 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e  es to be used in
151c0 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65   place of.** the
151d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
151e0 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c  on routines buil
151f0 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e  t into SQLite.)^
15200 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a   ^SQLite makes.*
15210 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  * its own privat
15220 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 63 6f  e copy of the co
15230 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
15240 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
15250 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20  s] structure.** 
15260 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71 6c 69  before the [sqli
15270 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61  te3_config()] ca
15280 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e  ll returns.</dd>
15290 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
152a0 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
152b0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
152c0 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f  NFIG_GETMALLOC</
152d0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
152e0 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
152f0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
15300 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
15310 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
15320 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
15330 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
15340 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
15350 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
15360 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
15370 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
15380 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
15390 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f  tly defined memo
153a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
153b0 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69  utines.)^.** Thi
153c0 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  s option can be 
153d0 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64  used to overload
153e0 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d   the default mem
153f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
15400 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
15410 61 20 77 72 61 70 70 65 72 20 74 68 61 74 20 73  a wrapper that s
15420 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72  imulations memor
15430 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
15440 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b  lure or.** track
15450 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2c 20  s memory usage, 
15460 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64  for example. </d
15470 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
15480 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
15490 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  US]] <dt>SQLITE_
154a0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
154b0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
154c0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
154d0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
154e0 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e   of type int, in
154f0 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a  terpreted as a .
15500 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63  ** boolean, whic
15510 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73  h enables or dis
15520 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63  ables the collec
15530 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61  tion of memory a
15540 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74  llocation .** st
15550 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e  atistics. ^(When
15560 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15570 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
15580 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20  e disabled, the 
15590 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51  .** following SQ
155a0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20  Lite interfaces 
155b0 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61  become non-opera
155c0 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c  tional:.**   <ul
155d0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  >.**   <li> [sql
155e0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
155f0 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ()].**   <li> [s
15600 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
15610 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20  ghwater()].**   
15620 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f  <li> [sqlite3_so
15630 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
15640 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
15650 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a  lite3_status()].
15660 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  **   </ul>)^.** 
15670 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  ^Memory allocati
15680 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72  on statistics ar
15690 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66  e enabled by def
156a0 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69  ault unless SQLi
156b0 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65  te is.** compile
156c0 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44  d with [SQLITE_D
156d0 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
156e0 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73  ]=0 in which cas
156f0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
15700 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
15710 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
15720 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f  y default..** </
15730 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15740 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
15750 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  H]] <dt>SQLITE_C
15760 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c 2f 64  ONFIG_SCRATCH</d
15770 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
15780 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
15790 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
157a0 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
157b0 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
157c0 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f  .** scratch memo
157d0 72 79 2e 20 20 54 68 65 72 65 20 61 72 65 20 74  ry.  There are t
157e0 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
157f0 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d   A pointer an 8-
15800 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20  byte.** aligned 
15810 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 66 72  memory buffer fr
15820 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73 63 72  om which the scr
15830 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  atch allocations
15840 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77   will be.** draw
15850 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65  n, the size of e
15860 61 63 68 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  ach scratch allo
15870 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20  cation (sz),.** 
15880 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  and the maximum 
15890 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61 74 63  number of scratc
158a0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e  h allocations (N
158b0 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72  ).  The sz.** ar
158c0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
158d0 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e   multiple of 16.
158e0 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72  .** The first ar
158f0 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 61  gument must be a
15900 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 38   pointer to an 8
15910 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 62 75  -byte aligned bu
15920 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65  ffer.** of at le
15930 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f  ast sz*N bytes o
15940 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51  f memory..** ^SQ
15950 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f  Lite will use no
15960 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f 20 73   more than two s
15970 63 72 61 74 63 68 20 62 75 66 66 65 72 73 20 70  cratch buffers p
15980 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a  er thread.  So.*
15990 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20 73 65  * N should be se
159a0 74 20 74 6f 20 74 77 69 63 65 20 74 68 65 20 65  t to twice the e
159b0 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75 6d 20  xpected maximum 
159c0 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65 61 64  number of thread
159d0 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  s..** ^SQLite wi
159e0 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69 72 65  ll never require
159f0 20 61 20 73 63 72 61 74 63 68 20 62 75 66 66 65   a scratch buffe
15a00 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65 20 74  r that is more t
15a10 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74  han 6.** times t
15a20 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65  he database page
15a30 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74   size. ^If SQLit
15a40 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20 61 64  e needs needs ad
15a50 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61  ditional.** scra
15a60 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e  tch memory beyon
15a70 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69 64  d what is provid
15a80 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e 66 69  ed by this confi
15a90 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c  guration option,
15aa0 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74   then .** [sqlit
15ab0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c  e3_malloc()] wil
15ac0 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  l be used to obt
15ad0 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e  ain the memory n
15ae0 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  eeded.</dd>.**.*
15af0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
15b00 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20 3c 64  G_PAGECACHE]] <d
15b10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15b20 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a  PAGECACHE</dt>.*
15b30 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74  * <dd> ^This opt
15b40 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20  ion specifies a 
15b50 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75  static memory bu
15b60 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  ffer that SQLite
15b70 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20   can use for.** 
15b80 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61 67  the database pag
15b90 65 20 63 61 63 68 65 20 77 69 74 68 20 74 68 65  e cache with the
15ba0 20 64 65 66 61 75 6c 74 20 70 61 67 65 20 63 61   default page ca
15bb0 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
15bc0 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f  on.  .** This co
15bd0 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68 6f 75  nfiguration shou
15be0 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64 20 69  ld not be used i
15bf0 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
15c00 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20  -define page.** 
15c10 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
15c20 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64 20 75  tion is loaded u
15c30 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  sing the SQLITE_
15c40 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20 6f  CONFIG_PCACHE2 o
15c50 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20  ption..** There 
15c60 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
15c70 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
15c80 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  on: A pointer to
15c90 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 0a   8-byte aligned.
15ca0 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73  ** memory, the s
15cb0 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61 67 65  ize of each page
15cc0 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20 61 6e   buffer (sz), an
15cd0 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
15ce0 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68  pages (N)..** Th
15cf0 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20 73 68  e sz argument sh
15d00 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69 7a 65  ould be the size
15d10 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
15d20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a 2a 2a  database page.**
15d30 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74 77 6f   (a power of two
15d40 20 62 65 74 77 65 65 6e 20 35 31 32 20 61 6e 64   between 512 and
15d50 20 33 32 37 36 38 29 20 70 6c 75 73 20 61 20 6c   32768) plus a l
15d60 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f 72 20  ittle extra for 
15d70 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68 65 61  each.** page hea
15d80 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67 65 20  der.  ^The page 
15d90 68 65 61 64 65 72 20 73 69 7a 65 20 69 73 20 32  header size is 2
15da0 30 20 74 6f 20 34 30 20 62 79 74 65 73 20 64 65  0 to 40 bytes de
15db0 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68  pending on.** th
15dc0 65 20 68 6f 73 74 20 61 72 63 68 69 74 65 63 74  e host architect
15dd0 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68 61 72  ure.  ^It is har
15de0 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66 72 6f  mless, apart fro
15df0 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d 65 6d  m the wasted mem
15e00 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20  ory,.** to make 
15e10 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20  sz a little too 
15e20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69 72 73  large.  The firs
15e30 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73 68  t.** argument sh
15e40 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e  ould point to an
15e50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61   allocation of a
15e60 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
15e70 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
15e80 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
15e90 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f  e the memory pro
15ea0 76 69 64 65 64 20 62 79 20 74 68 65 20 66 69 72  vided by the fir
15eb0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
15ec0 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65  atisfy its.** me
15ed0 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72 20 74  mory needs for t
15ee0 68 65 20 66 69 72 73 74 20 4e 20 70 61 67 65 73  he first N pages
15ef0 20 74 68 61 74 20 69 74 20 61 64 64 73 20 74 6f   that it adds to
15f00 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61 64 64   cache.  ^If add
15f10 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20  itional.** page 
15f20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20  cache memory is 
15f30 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20 77 68  needed beyond wh
15f40 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20 62  at is provided b
15f50 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74  y this option, t
15f60 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f  hen.** SQLite go
15f70 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d  es to [sqlite3_m
15f80 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74 68 65  alloc()] for the
15f90 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72   additional stor
15fa0 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68  age space..** Th
15fb0 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65  e pointer in the
15fc0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15fd0 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e  must.** be align
15fe0 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  ed to an 8-byte 
15ff0 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73  boundary or subs
16000 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20  equent behavior 
16010 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  of SQLite.** wil
16020 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c  l be undefined.<
16030 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
16040 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d  ITE_CONFIG_HEAP]
16050 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16060 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
16070 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
16080 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
16090 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
160a0 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
160b0 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
160c0 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
160d0 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
160e0 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
160f0 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
16100 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
16110 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
16120 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
16130 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
16140 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
16150 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
16160 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
16170 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
16180 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
16190 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
161a0 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
161b0 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
161c0 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
161d0 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
161e0 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
161f0 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
16200 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
16210 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
16220 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
16230 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
16240 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
16250 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
16260 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
16270 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
16280 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
16290 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
162a0 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
162b0 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
162c0 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
162d0 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
162e0 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
162f0 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
16300 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
16310 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
16320 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
16330 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
16340 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
16350 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
16360 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
16370 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
16380 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
16390 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
163a0 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
163b0 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
163c0 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
163d0 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
163e0 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
163f0 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
16400 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
16410 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
16420 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
16430 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31 32 2e  capped at 2**12.
16440 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75   Reasonable valu
16450 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69  es.** for the mi
16460 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
16470 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35 20 74   size are 2**5 t
16480 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64  hrough 2**8.</dd
16490 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
164a0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20  _CONFIG_MUTEX]] 
164b0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
164c0 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  G_MUTEX</dt>.** 
164d0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
164e0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
164f0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
16500 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
16510 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
16520 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
16530 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
16540 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61  tructure.  The a
16550 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65  rgument specifie
16560 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65  s.** alternative
16570 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78   low-level mutex
16580 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
16590 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a  used in place.**
165a0 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69   the mutex routi
165b0 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  nes built into S
165c0 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74  QLite.)^  ^SQLit
165d0 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f  e makes a copy o
165e0 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74  f the.** content
165f0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
16600 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20  _mutex_methods] 
16610 73 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65  structure before
16620 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
16630 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
16640 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20  )] returns. ^If 
16650 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
16660 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
16670 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
16680 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
16690 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
166a0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
166b0 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
166c0 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
166d0 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
166e0 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
166f0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
16700 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
16710 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
16720 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16730 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
16740 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
16750 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
16760 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
16770 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
16780 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74  G_GETMUTEX]] <dt
16790 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
167a0 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20  ETMUTEX</dt>.** 
167b0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
167c0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
167d0 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
167e0 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
167f0 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20   an.** instance 
16800 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
16810 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
16820 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a  tructure.  The.*
16830 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  * [sqlite3_mutex
16840 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72  _methods].** str
16850 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64  ucture is filled
16860 20 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e   with the curren
16870 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65  tly defined mute
16880 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  x routines.)^.**
16890 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
168a0 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
168b0 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
168c0 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f   mutex allocatio
168d0 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69  n.** routines wi
168e0 74 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65  th a wrapper use
168f0 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78  d to track mutex
16900 20 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f   usage for perfo
16910 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c  rmance.** profil
16920 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20  ing or testing, 
16930 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e  for example.   ^
16940 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
16950 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
16960 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
16970 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
16980 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
16990 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
169a0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69  then.** the enti
169b0 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73  re mutexing subs
169c0 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64  ystem is omitted
169d0 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20   from the build 
169e0 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20  and hence calls 
169f0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
16a00 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68  onfig()] with th
16a10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
16a20 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  GETMUTEX configu
16a30 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
16a40 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
16a50 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
16a60 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
16a70 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
16a80 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
16a90 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
16aa0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54  /dt>.** <dd> ^(T
16ab0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
16ac0 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74   two arguments t
16ad0 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68  hat determine th
16ae0 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d  e default.** mem
16af0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
16b00 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  or the lookaside
16b10 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
16b20 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61  r on each.** [da
16b30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
16b40 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61  n].  The first a
16b50 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a  rgument is the.*
16b60 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c  * size of each l
16b70 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20  ookaside buffer 
16b80 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63  slot and the sec
16b90 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ond is the numbe
16ba0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c  r of.** slots al
16bb0 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20  located to each 
16bc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
16bd0 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f  ion.)^  ^(This o
16be0 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a  ption sets the.*
16bf0 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e  * <i>default</i>
16c00 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e   lookaside size.
16c10 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43   The [SQLITE_DBC
16c20 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
16c30 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c  .** verb to [sql
16c40 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
16c50 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  ] can be used to
16c60 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
16c70 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75  aside.** configu
16c80 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69  ration on indivi
16c90 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  dual connections
16ca0 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
16cb0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16cc0 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
16cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16ce0 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  HE2</dt>.** <dd>
16cf0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
16d00 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
16d10 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
16d20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
16d30 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63  an [sqlite3_pcac
16d40 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a  he_methods2] obj
16d50 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a 65 63  ect.  This objec
16d60 74 20 73 70 65 63 69 66 69 65 73 20 74 68 65 20  t specifies the 
16d70 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20  interface.** to 
16d80 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20 63 61  a custom page ca
16d90 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
16da0 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  on.)^  ^SQLite m
16db0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
16dc0 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64  he.** object and
16dd0 20 75 73 65 73 20 69 74 20 66 6f 72 20 70 61 67   uses it for pag
16de0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
16df0 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e  llocations.</dd>
16e00 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16e10 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
16e20 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
16e30 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
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 20 61 6e 0a 2a 2a 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 53 51 4c 69 74 65 20 63 6f 70 69 65 73  .  SQLite copies
16ec0 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
16ed0 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ** page cache im
16ee0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74  plementation int
16ef0 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e  o that object.)^
16f00 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
16f10 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
16f20 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16f30 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a  NFIG_LOG</dt>.**
16f40 20 3c 64 64 3e 20 5e 54 68 65 20 53 51 4c 49 54   <dd> ^The SQLIT
16f50 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74  E_CONFIG_LOG opt
16f60 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72  ion takes two ar
16f70 67 75 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74  guments: a point
16f80 65 72 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74  er to a.** funct
16f90 69 6f 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20  ion with a call 
16fa0 73 69 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69  signature of voi
16fb0 64 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  d(*)(void*,int,c
16fc0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a  onst char*), .**
16fd0 20 61 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74   and a pointer t
16fe0 6f 20 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20  o void. ^If the 
16ff0 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
17000 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74   is not NULL, it
17010 20 69 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62   is.** invoked b
17020 79 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  y [sqlite3_log()
17030 5d 20 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63  ] to process eac
17040 68 20 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e  h logging event.
17050 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e    ^If the.** fun
17060 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
17070 20 4e 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69   NULL, the [sqli
17080 74 65 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72  te3_log()] inter
17090 66 61 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e  face becomes a n
170a0 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f  o-op..** ^The vo
170b0 69 64 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20  id pointer that 
170c0 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  is the second ar
170d0 67 75 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45  gument to SQLITE
170e0 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a  _CONFIG_LOG is.*
170f0 2a 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68  * passed through
17100 20 61 73 20 74 68 65 20 66 69 72 73 74 20 70 61   as the first pa
17110 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61  rameter to the a
17120 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
17130 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
17140 63 74 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74  ction whenever t
17150 68 61 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  hat function is 
17160 69 6e 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73  invoked.  ^The s
17170 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
17180 74 6f 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72  to.** the logger
17190 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63   function is a c
171a0 6f 70 79 20 6f 66 20 74 68 65 20 66 69 72 73 74  opy of the first
171b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
171c0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a  e corresponding.
171d0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28  ** [sqlite3_log(
171e0 29 5d 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69  )] call and is i
171f0 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20  ntended to be a 
17200 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
17210 20 61 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   an.** [extended
17220 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20   result code].  
17230 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
17240 65 74 65 72 20 70 61 73 73 65 64 20 74 6f 20 74  eter passed to t
17250 68 65 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20  he logger is.** 
17260 6c 6f 67 20 6d 65 73 73 61 67 65 20 61 66 74 65  log message afte
17270 72 20 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61  r formatting via
17280 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
17290 74 66 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51  tf()]..** The SQ
172a0 4c 69 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74  Lite logging int
172b0 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65  erface is not re
172c0 65 6e 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67  entrant; the log
172d0 67 65 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ger function.** 
172e0 73 75 70 70 6c 69 65 64 20 62 79 20 74 68 65 20  supplied by the 
172f0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
17300 20 6e 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20   not invoke any 
17310 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
17320 2e 0a 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d  ..** In a multi-
17330 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
17340 74 69 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63  tion, the applic
17350 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f  ation-defined lo
17360 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gger.** function
17370 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
17380 61 66 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  afe. </dd>.**.**
17390 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
173a0 5f 55 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  _URI]] <dt>SQLIT
173b0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20  E_CONFIG_URI.** 
173c0 3c 64 64 3e 20 54 68 69 73 20 6f 70 74 69 6f 6e  <dd> This option
173d0 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
173e0 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65  argument of type
173f0 20 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72   int. If non-zer
17400 6f 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68  o, then.** URI h
17410 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
17420 6c 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20  lly enabled. If 
17430 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
17440 20 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20   zero, then URI 
17450 68 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67  handling.** is g
17460 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
17470 2e 20 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e  . If URI handlin
17480 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
17490 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e  abled, all filen
174a0 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74  ames.** passed t
174b0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
174c0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
174d0 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65  n_v2()], [sqlite
174e0 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a  3_open16()] or.*
174f0 2a 20 73 70 65 63 69 66 69 65 64 20 61 73 20 70  * specified as p
17500 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20  art of [ATTACH] 
17510 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74  commands are int
17520 65 72 70 72 65 74 65 64 20 61 73 20 55 52 49 73  erpreted as URIs
17530 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20  , regardless.** 
17540 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
17550 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  t the [SQLITE_OP
17560 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20  EN_URI] flag is 
17570 73 65 74 20 77 68 65 6e 20 74 68 65 20 64 61 74  set when the dat
17580 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
17590 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 49  ion is opened. I
175a0 66 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79  f it is globally
175b0 20 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e   disabled, filen
175c0 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79  ames are.** only
175d0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
175e0 55 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49  URIs if the SQLI
175f0 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67  TE_OPEN_URI flag
17600 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65   is set when the
17610 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
17620 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65  nection is opene
17630 64 2e 20 42 79 20 64 65 66 61 75 6c 74 2c 20 55  d. By default, U
17640 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
17650 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61 62  lobally.** disab
17660 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c 74  led. The default
17670 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63 68   value may be ch
17680 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c 69  anged by compili
17690 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  ng with the.** [
176a0 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d 20  SQLITE_USE_URI] 
176b0 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e 0a  symbol defined..
176c0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
176d0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
176e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
176f0 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
17700 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17710 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
17720 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
17730 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
17740 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
17750 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
17760 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
17770 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
17780 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
17790 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
177a0 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
177b0 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
177c0 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </dl>.*/.#defi
177d0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
177e0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31  _SINGLETHREAD  1
177f0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
17800 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
17810 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20  G_MULTITHREAD   
17820 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  2  /* nil */.#de
17830 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17840 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20  IG_SERIALIZED   
17850 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   3  /* nil */.#d
17860 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
17870 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20  FIG_MALLOC      
17880 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f    4  /* sqlite3_
17890 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  mem_methods* */.
178a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
178b0 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20  ONFIG_GETMALLOC 
178c0 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65      5  /* sqlite
178d0 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
178e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
178f0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20  _CONFIG_SCRATCH 
17900 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64        6  /* void
17910 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e  *, int sz, int N
17920 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17930 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
17940 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f  CHE     7  /* vo
17950 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
17960 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
17970 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50  LITE_CONFIG_HEAP
17980 20 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20            8  /* 
17990 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65  void*, int nByte
179a0 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65  , int min */.#de
179b0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
179c0 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20  IG_MEMSTATUS    
179d0 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a   9  /* boolean *
179e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
179f0 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20  _CONFIG_MUTEX   
17a00 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69       10  /* sqli
17a10 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64  te3_mutex_method
17a20 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
17a30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
17a40 55 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20  UTEX     11  /* 
17a50 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
17a60 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65  thods* */./* pre
17a70 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43  viously SQLITE_C
17a80 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43  ONFIG_CHUNKALLOC
17a90 20 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77   12 which is now
17aa0 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65   unused. */ .#de
17ab0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
17ac0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20  IG_LOOKASIDE    
17ad0 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a  13  /* int int *
17ae0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17af0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20  _CONFIG_PCACHE  
17b00 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f       14  /* no-o
17b10 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  p */.#define SQL
17b20 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
17b30 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e  ACHE    15  /* n
17b40 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20  o-op */.#define 
17b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
17b60 47 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f  G          16  /
17b70 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a  * xFunc, void* *
17b80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17b90 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20  _CONFIG_URI     
17ba0 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20       17  /* int 
17bb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17bc0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
17bd0 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c        18  /* sql
17be0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
17bf0 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  ods2* */.#define
17c00 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
17c10 45 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20  ETPCACHE2   19  
17c20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
17c30 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 0a  e_methods2* */..
17c40 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17c50 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
17c60 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
17c70 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
17c80 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
17c90 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
17ca0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
17cb0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
17cc0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
17cd0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
17ce0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
17cf0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
17d00 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
17d10 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
17d20 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
17d30 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
17d40 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
17d50 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
17d60 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
17d70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
17d80 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
17d90 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
17da0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
17db0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
17dc0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
17dd0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
17de0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
17df0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
17e00 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
17e10 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
17e20 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
17e30 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
17e40 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
17e50 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
17e60 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
17e70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
17e80 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
17e90 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
17ea0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
17eb0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
17ec0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
17ed0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
17ee0 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
17ef0 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
17f00 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
17f10 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
17f20 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
17f30 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
17f40 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
17f50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
17f60 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
17f70 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
17f80 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
17f90 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
17fa0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
17fb0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
17fc0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
17fd0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
17fe0 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
17ff0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
18000 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
18010 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18020 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
18030 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
18040 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
18050 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
18060 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
18070 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
18080 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18090 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
180a0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
180b0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
180c0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
180d0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
180e0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
180f0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
18100 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
18110 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
18120 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18130 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
18140 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
18150 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
18160 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
18170 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
18180 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
18190 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
181a0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
181b0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
181c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
181d0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
181e0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
181f0 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
18200 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
18210 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
18220 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
18230 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
18240 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
18250 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
18260 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
18270 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
18280 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18290 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
182a0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
182b0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
182c0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
182d0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
182e0 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
182f0 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
18300 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
18310 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
18320 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
18330 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
18340 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
18350 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
18360 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
18370 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
18380 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
18390 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
183a0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
183b0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
183c0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
183d0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
183e0 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
183f0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
18400 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
18410 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18420 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
18430 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
18440 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
18450 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
18460 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
18470 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
18480 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
18490 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
184a0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
184b0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
184c0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
184d0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
184e0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
184f0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
18500 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
18510 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
18520 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
18530 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
18540 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
18550 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
18560 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
18570 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18580 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18590 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
185a0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
185b0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
185c0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
185d0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
185e0 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
185f0 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
18600 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18610 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
18620 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
18630 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
18640 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
18650 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
18660 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
18670 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
18680 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
18690 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
186a0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
186b0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
186c0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
186d0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
186e0 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
186f0 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
18700 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
18710 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
18720 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
18730 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
18740 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
18750 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
18760 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
18770 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
18780 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
18790 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
187a0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
187b0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
187c0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
187d0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
187e0 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
187f0 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
18800 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
18810 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
18820 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
18830 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
18840 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
18850 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18860 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
18870 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
18880 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
18890 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
188a0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
188b0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
188c0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
188d0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
188e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
188f0 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
18900 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
18910 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
18920 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
18930 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
18940 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
18950 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
18960 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
18970 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
18980 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
18990 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
189a0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
189b0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
189c0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
189d0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
189e0 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
189f0 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
18a00 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
18a10 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
18a20 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
18a30 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
18a40 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
18a50 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
18a60 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
18a70 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
18a80 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
18a90 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
18aa0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
18ab0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
18ac0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
18ad0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18ae0 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
18af0 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  Rowid.**.** ^Eac
18b00 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
18b10 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
18b20 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
18b30 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
18b40 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
18b50 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
18b60 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
18b70 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
18b80 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
18b90 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
18ba0 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
18bb0 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
18bc0 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
18bd0 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
18be0 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
18bf0 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
18c00 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
18c10 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
18c20 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
18c30 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
18c40 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
18c50 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
18c60 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
18c70 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  owid..**.** ^Thi
18c80 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
18c90 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
18ca0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
18cb0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
18cc0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65  INSERT] into the
18cd0 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
18ce0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
18cf0 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
18d00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18d10 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74  t.  ^As of SQLit
18d20 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
18d30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a   this routines.*
18d40 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61  * records the la
18d50 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20  st insert rowid 
18d60 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79  of both ordinary
18d70 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72   tables and [vir
18d80 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a  tual tables]..**
18d90 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
18da0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
18db0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
18dc0 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
18dd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
18de0 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
18df0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
18e00 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
18e10 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
18e20 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69   or within a [vi
18e30 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
18e40 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69  method, then thi
18e50 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  s routine will r
18e60 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
18e70 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
18e80 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67  d.** row as long
18e90 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
18ea0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
18eb0 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69   method is runni
18ec0 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
18ed0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
18ee0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
18ef0 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61  hod ends, the va
18f00 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
18f10 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
18f20 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
18f30 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
18f40 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
18f50 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d  rtual.** table m
18f60 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a  ethod began.)^.*
18f70 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
18f80 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
18f90 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
18fa0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
18fb0 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
18fc0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
18fd0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
18fe0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
18ff0 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
19000 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
19010 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
19020 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
19030 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
19040 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
19050 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
19060 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
19070 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
19080 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
19090 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
190a0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
190b0 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
190c0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
190d0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
190e0 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
190f0 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
19100 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
19110 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
19120 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
19130 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
19140 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
19150 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
19160 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
19170 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
19180 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
19190 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
191a0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
191b0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
191c0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
191d0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
191e0 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
191f0 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
19200 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
19210 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
19220 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
19230 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
19240 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
19250 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
19260 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
19270 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19280 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
19290 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
192a0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
192b0 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
192c0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
192d0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
192e0 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
192f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
19300 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19310 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
19320 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
19330 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
19340 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
19350 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
19360 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19370 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
19380 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
19390 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
193a0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
193b0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
193c0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
193d0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
193e0 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  rowid]..*/.SQLIT
193f0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
19400 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
19410 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
19420 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19430 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
19440 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
19450 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
19460 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
19470 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
19480 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
19490 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
194a0 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
194b0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
194c0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
194d0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
194e0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
194f0 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
19500 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
19510 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
19520 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
19530 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65  ** ^(Only change
19540 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
19550 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
19560 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
19570 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
19580 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
19590 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
195a0 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
195b0 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
195c0 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65  riggers or [fore
195d0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
195e0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
195f0 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  .)^ Use the.** [
19600 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
19610 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
19620 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
19630 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
19640 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
19650 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
19660 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
19670 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
19680 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68  tions..**.** ^Ch
19690 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
196a0 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74  that are simulat
196b0 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41  ed by an [INSTEA
196c0 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a  D OF trigger].**
196d0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
196e0 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62  .  Only real tab
196f0 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  le changes are c
19700 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ounted..**.** ^(
19710 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
19720 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
19730 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
19740 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
19750 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
19760 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
19770 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
19780 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
19790 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
197a0 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
197b0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
197c0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
197d0 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
197e0 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
197f0 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
19800 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
19810 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
19820 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
19830 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e  t row changes.)^
19840 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
19850 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
19860 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
19870 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
19880 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
19890 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
198a0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
198b0 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
198c0 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
198d0 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
198e0 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
198f0 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
19900 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
19910 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
19920 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
19930 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
19940 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
19950 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
19960 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
19970 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
19980 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
19990 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
199a0 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
199b0 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
199c0 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
199d0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  n..**.** ^Callin
199e0 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
199f0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
19a00 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
19a10 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
19a20 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
19a30 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
19a40 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
19a50 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
19a60 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
19a70 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
19a80 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
19a90 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
19aa0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
19ab0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
19ac0 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
19ad0 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
19ae0 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
19af0 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
19b00 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
19b10 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
19b20 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
19b30 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
19b40 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
19b50 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
19b60 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
19b70 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
19b80 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74  op level.  ^(Wit
19b90 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
19ba0 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
19bb0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
19bc0 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
19bd0 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
19be0 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
19bf0 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
19c00 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
19c10 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
19c20 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
19c30 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
19c40 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
19c50 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
19c60 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
19c70 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
19c80 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
19c90 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
19ca0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
19cb0 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
19cc0 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
19cd0 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a   own context.)^.
19ce0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
19cf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
19d00 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
19d10 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
19d20 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
19d30 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
19d40 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
19d50 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
19d60 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
19d70 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
19d80 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
19d90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
19da0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
19db0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
19dc0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
19dd0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19de0 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
19df0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
19e00 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  aningful..*/.SQL
19e10 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
19e20 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
19e30 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
19e40 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
19e50 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
19e60 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
19e70 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
19e80 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
19e90 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
19ea0 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c  sed by [INSERT],
19eb0 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  .** [UPDATE] or 
19ec0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
19ed0 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
19ee0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
19ef0 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
19f00 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72  ** ^(The count r
19f10 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
19f20 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
19f30 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
19f40 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20  changes.** from 
19f50 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47  all [CREATE TRIG
19f60 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63  GER | trigger] c
19f70 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e  ontexts and chan
19f80 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b  ges made by.** [
19f90 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
19fa0 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a  ons]. However,.*
19fb0 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  * the count does
19fc0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
19fd0 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70  nges used to imp
19fe0 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d  lement [REPLACE]
19ff0 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
1a000 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
1a010 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
1a020 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c  g, or [DROP TABL
1a030 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20  E] processing.  
1a040 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65  The.** count doe
1a050 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f  s not include ro
1a060 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74  ws of views that
1a070 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41   fire an [INSTEA
1a080 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a  D OF trigger],.*
1a090 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20  * though if the 
1a0a0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1a0b0 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  er makes changes
1a0c0 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f   of its own, tho
1a0d0 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61  se changes .** a
1a0e0 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a  re counted.)^.**
1a0f0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f   ^The sqlite3_to
1a100 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75  tal_changes() fu
1a110 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68  nction counts th
1a120 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f  e changes as soo
1a130 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74  n as.** the stat
1a140 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
1a150 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74   them is complet
1a160 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
1a170 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a  tement handle.**
1a180 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
1a190 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1a1a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
1a1b0 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
1a1c0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
1a1d0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
1a1e0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
1a1f0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
1a200 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
1a210 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
1a220 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1a230 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1a240 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
1a250 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
1a260 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1a270 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
1a280 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
1a290 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
1a2a0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
1a2b0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
1a2c0 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
1a2d0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
1a2e0 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  aningful..*/.SQL
1a2f0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1a300 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1a310 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1a320 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
1a330 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
1a340 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
1a350 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1a360 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1a370 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1a380 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1a390 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1a3a0 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1a3b0 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1a3c0 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1a3d0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1a3e0 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1a3f0 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1a400 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1a410 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1a420 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1a430 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1a440 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1a450 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1a460 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1a470 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1a480 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1a490 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1a4a0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1a4b0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1a4c0 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1a4d0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1a4e0 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1a4f0 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1a500 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1a510 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1a520 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1a530 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1a540 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1a550 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1a560 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1a570 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1a580 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1a590 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1a5a0 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1a5b0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1a5c0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1a5d0 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1a5e0 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1a5f0 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1a600 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1a610 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1a620 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1a630 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1a640 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1a650 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1a660 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1a670 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1a680 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1a690 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1a6a0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1a6b0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1a6c0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1a6d0 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1a6e0 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1a6f0 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1a700 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1a710 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1a720 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1a730 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1a740 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1a750 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1a760 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1a770 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1a780 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1a790 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1a7a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a7b0 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1a7c0 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1a7d0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1a7e0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1a7f0 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1a800 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1a810 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1a820 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1a830 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1a840 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1a850 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1a860 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1a870 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1a880 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a890 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1a8a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1a8b0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1a8c0 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1a8d0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1a8e0 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1a8f0 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1a900 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1a910 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1a920 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1a930 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1a940 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1a950 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1a960 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1a970 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1a980 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1a990 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1a9a0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1a9b0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1a9c0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1a9d0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1a9e0 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
1a9f0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1aa00 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
1aa10 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
1aa20 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
1aa30 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
1aa40 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
1aa50 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
1aa60 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1aa70 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1aa80 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1aa90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1aaa0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1aab0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1aac0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1aad0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1aae0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1aaf0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1ab00 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1ab10 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1ab20 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1ab30 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1ab40 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1ab50 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1ab60 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1ab70 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1ab80 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1ab90 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1aba0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1abb0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1abc0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1abd0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1abe0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1abf0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1ac00 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1ac10 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1ac20 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1ac30 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1ac40 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1ac50 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1ac60 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1ac70 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1ac80 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1ac90 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1aca0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1acb0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1acc0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1acd0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1ace0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1acf0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1ad00 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1ad10 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1ad20 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1ad30 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1ad40 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1ad50 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1ad60 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1ad70 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1ad80 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1ad90 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1ada0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1adb0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1adc0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1add0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1ade0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1adf0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1ae00 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1ae10 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1ae20 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1ae30 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1ae40 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1ae50 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1ae60 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1ae70 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1ae80 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1ae90 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1aea0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1aeb0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1aec0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1aed0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1aee0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1aef0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1af00 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1af10 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1af20 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1af30 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1af40 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1af50 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1af60 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1af70 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1af80 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1af90 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1afa0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1afb0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1afc0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1afd0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1afe0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1aff0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1b000 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1b010 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1b020 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1b030 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b040 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1b050 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1b060 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1b070 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1b080 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1b090 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1b0a0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1b0b0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1b0c0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1b0d0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c  te order..*/.SQL
1b0e0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1b0f0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
1b100 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53  st char *sql);.S
1b110 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1b120 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1b130 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
1b140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b150 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
1b160 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
1b170 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
1b180 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  rors.**.** ^This
1b190 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1b1a0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1b1b0 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  n that might be 
1b1c0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
1b1d0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
1b1e0 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61  s made to open a
1b1f0 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
1b200 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
1b210 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
1b220 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
1b230 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
1b240 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1b250 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
1b260 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
1b270 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
1b280 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1b290 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
1b2a0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
1b2b0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
1b2c0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
1b2d0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
1b2e0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1b2f0 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1b300 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
1b310 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1b320 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1b330 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
1b340 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
1b350 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
1b360 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
1b370 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1b380 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
1b390 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
1b3a0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1b3b0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
1b3c0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1b3d0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
1b3e0 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
1b3f0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
1b400 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
1b410 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
1b420 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
1b430 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
1b440 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
1b450 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
1b460 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
1b470 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
1b480 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1b490 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
1b4a0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
1b4b0 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
1b4c0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  turned..** ^If t
1b4d0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1b4e0 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1b4f0 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
1b500 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
1b510 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
1b520 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
1b530 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
1b540 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
1b550 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
1b560 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
1b570 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
1b580 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
1b590 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
1b5a0 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
1b5b0 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
1b5c0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
1b5d0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
1b5e0 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
1b5f0 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
1b600 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
1b610 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
1b620 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1b630 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
1b640 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
1b650 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
1b660 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
1b670 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1b680 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1b690 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1b6a0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1b6b0 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1b6c0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1b6d0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1b6e0 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1b6f0 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1b700 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1b710 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1b720 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1b730 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1b740 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1b750 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1b760 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1b770 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1b780 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1b790 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1b7a0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1b7b0 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1b7c0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1b7d0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1b7e0 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1b7f0 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1b800 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1b810 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1b820 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1b830 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1b840 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1b850 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1b860 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1b870 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1b880 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1b890 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1b8a0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1b8b0 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1b8c0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1b8d0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1b8e0 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1b8f0 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1b900 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1b910 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1b920 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
1b930 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
1b940 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
1b950 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
1b960 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
1b970 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
1b980 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
1b990 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
1b9a0 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
1b9b0 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
1b9c0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
1b9d0 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
1b9e0 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
1b9f0 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
1ba00 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
1ba10 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
1ba20 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
1ba30 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
1ba40 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
1ba50 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
1ba60 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
1ba70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
1ba80 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
1ba90 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
1baa0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
1bab0 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e  s.  ^If it is un
1bac0 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20  able to promote 
1bad0 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74  the lock, then t
1bae0 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  he in-memory.** 
1baf0 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65  cache will be le
1bb00 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69  ft in an inconsi
1bb10 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20  stent state and 
1bb20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  so the error.** 
1bb30 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64  code is promoted
1bb40 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69   from the relati
1bb50 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c  vely benign [SQL
1bb60 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20  ITE_BUSY] to.** 
1bb70 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  the more severe 
1bb80 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
1bb90 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65  OCKED].  ^This e
1bba0 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
1bbb0 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
1bbc0 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
1bbd0 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
1bbe0 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
1bbf0 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
1bc00 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
1bc10 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
1bc20 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
1bc30 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
1bc40 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
1bc50 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
1bc60 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
1bc70 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
1bc80 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  nt..**.** ^(Ther
1bc90 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1bca0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1bcb0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1bcc0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1bcd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1bce0 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1bcf0 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1bd00 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1bd10 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1bd20 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1bd30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1bd40 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1bd50 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
1bd60 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
1bd70 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
1bd80 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
1bd90 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
1bda0 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
1bdb0 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
1bdc0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1bdd0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1bde0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1bdf0 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68  ndler.  Any such
1be00 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
1be10 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
1be20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
1be30 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
1be40 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
1be50 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1be60 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
1be70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1be80 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
1be90 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1bea0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1beb0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1bec0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1bed0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
1bee0 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
1bef0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1bf00 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
1bf10 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1bf20 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
1bf30 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1bf40 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
1bf50 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
1bf60 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
1bf70 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1bf80 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
1bf90 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
1bfa0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
1bfb0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
1bfc0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
1bfd0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1bfe0 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
1bff0 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
1c000 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
1c010 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1c020 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1c030 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
1c040 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
1c050 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
1c060 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
1c070 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
1c080 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
1c090 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
1c0a0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1c0b0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1c0c0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1c0d0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1c0e0 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1c0f0 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1c100 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1c110 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1c120 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1c130 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1c140 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1c150 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1c160 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
1c170 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
1c180 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1c190 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
1c1a0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
1c1b0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1c1c0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
1c1d0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
1c1e0 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
1c1f0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1c200 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53   cleared.)^.*/.S
1c210 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1c220 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1c230 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
1c240 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
1c250 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
1c260 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
1c270 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
1c280 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1c290 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1c2a0 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1c2b0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1c2c0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1c2d0 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1c2e0 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1c2f0 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1c300 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1c310 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1c320 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1c330 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1c340 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1c350 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1c360 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1c370 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1c380 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1c390 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1c3a0 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1c3b0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1c3c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1c3d0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1c3e0 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1c3f0 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1c400 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1c410 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1c420 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1c430 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1c440 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1c450 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1c460 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1c470 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1c480 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1c490 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1c4a0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1c4b0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1c4c0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1c4d0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1c4e0 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1c4f0 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1c500 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1c510 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1c520 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1c530 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1c540 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1c550 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1c560 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1c570 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1c580 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1c590 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1c5a0 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1c5b0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1c5c0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1c5d0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1c5e0 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1c5f0 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1c600 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1c610 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1c620 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1c630 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1c640 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1c650 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1c660 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1c670 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1c680 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1c690 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1c6a0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1c6b0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1c6c0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1c6d0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1c6e0 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1c6f0 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1c700 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1c710 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1c720 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1c730 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1c740 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1c750 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1c760 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1c770 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1c780 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1c790 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1c7a0 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1c7b0 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1c7c0 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1c7d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1c7e0 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1c7f0 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1c800 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1c810 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1c820 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1c830 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1c840 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1c850 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1c860 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1c870 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1c880 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1c890 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1c8a0 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1c8b0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1c8c0 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1c8d0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1c8e0 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1c8f0 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1c900 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1c910 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1c920 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1c930 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1c940 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1c950 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1c960 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1c970 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1c980 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1c990 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1c9a0 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1c9b0 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1c9c0 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1c9d0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1c9e0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1c9f0 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1ca00 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1ca10 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1ca20 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1ca30 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1ca40 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1ca50 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1ca60 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1ca70 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1ca80 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1ca90 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1caa0 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1cab0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1cac0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1cad0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1cae0 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1caf0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1cb00 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1cb10 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1cb20 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1cb30 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1cb40 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1cb50 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1cb60 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1cb70 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1cb80 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1cb90 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1cba0 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1cbb0 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1cbc0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1cbd0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1cbe0 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1cbf0 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1cc00 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1cc10 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1cc20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1cc30 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1cc40 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1cc50 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1cc60 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1cc70 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1cc80 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1cc90 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1cca0 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1ccb0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1ccc0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1ccd0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1cce0 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1ccf0 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1cd00 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1cd10 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1cd20 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1cd30 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1cd40 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1cd50 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1cd60 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1cd70 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1cd80 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1cd90 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1cda0 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1cdb0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1cdc0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1cdd0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1cde0 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1cdf0 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1ce00 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1ce10 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1ce20 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1ce30 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1ce40 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1ce50 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1ce60 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1ce70 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1ce80 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1ce90 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1cea0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1ceb0 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  g()]..*/.SQLITE_
1cec0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1ced0 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1cee0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1cef0 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1cf00 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1cf10 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1cf20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1cf30 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1cf40 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1cf50 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1cf60 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1cf70 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1cf80 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1cf90 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1cfa0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1cfb0 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1cfc0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1cfd0 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1cfe0 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1cff0 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1d000 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1d010 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1d020 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49   here */.);.SQLI
1d030 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
1d040 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1d050 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1d060 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1d070 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1d080 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1d090 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1d0a0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1d0b0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1d0c0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1d0d0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1d0e0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1d0f0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1d100 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1d110 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1d120 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1d130 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1d140 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1d150 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1d160 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1d170 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1d180 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1d190 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1d1a0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1d1b0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1d1c0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1d1d0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1d1e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1d1f0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1d200 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1d210 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1d220 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1d230 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1d240 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1d250 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1d260 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1d270 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1d280 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1d290 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1d2a0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1d2b0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1d2c0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1d2d0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1d2e0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1d2f0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1d300 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1d310 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1d320 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1d330 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1d340 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1d350 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1d360 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1d370 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1d380 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1d390 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1d3a0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1d3b0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1d3c0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1d3d0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1d3e0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1d3f0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1d400 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1d410 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1d420 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1d430 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1d440 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1d450 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1d460 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1d470 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1d480 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1d490 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1d4a0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1d4b0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1d4c0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1d4d0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1d4e0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1d4f0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1d500 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1d510 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1d520 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1d530 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1d540 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1d550 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1d560 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1d570 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1d580 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1d590 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1d5a0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1d5b0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1d5c0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1d5d0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1d5e0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1d5f0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1d600 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1d610 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1d620 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1d630 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1d640 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1d650 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1d660 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1d670 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1d680 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1d690 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1d6a0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1d6b0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1d6c0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d6d0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1d6e0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1d6f0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1d700 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1d710 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1d720 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1d730 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1d740 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1d750 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1d760 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1d770 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1d780 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1d790 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1d7a0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1d7b0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1d7c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1d7d0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1d7e0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1d7f0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1d800 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1d810 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1d820 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1d830 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1d840 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1d850 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1d860 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1d870 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1d880 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1d890 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1d8a0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1d8b0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1d8c0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1d8d0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1d8e0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1d8f0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1d900 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1d910 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1d920 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1d930 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1d940 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1d950 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1d960 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1d970 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1d980 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1d990 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1d9a0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1d9b0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1d9c0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1d9d0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1d9e0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1d9f0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1da00 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1da10 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1da20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1da30 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1da40 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1da50 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1da60 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1da70 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1da80 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1da90 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1daa0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1dab0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1dac0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1dad0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1dae0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1daf0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1db00 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1db10 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1db20 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1db30 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1db40 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1db50 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1db60 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1db70 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1db80 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1db90 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1dba0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1dbb0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1dbc0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1dbd0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1dbe0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1dbf0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1dc00 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1dc10 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1dc20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1dc30 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1dc40 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1dc50 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1dc60 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1dc70 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1dc80 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1dc90 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1dca0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1dcb0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1dcc0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1dcd0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1dce0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1dcf0 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1dd00 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1dd10 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1dd20 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1dd30 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1dd40 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1dd50 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1dd60 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1dd70 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1dd80 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1dd90 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1dda0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1ddb0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1ddc0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1ddd0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1dde0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1ddf0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1de00 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1de10 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1de20 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1de30 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1de40 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1de50 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1de60 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1de70 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1de80 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1de90 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1dea0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1deb0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1dec0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1ded0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1dee0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1def0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1df00 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1df10 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1df20 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1df30 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1df40 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1df50 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1df60 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1df70 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1df80 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1df90 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1dfa0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1dfb0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1dfc0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1dfd0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1dfe0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54  ring.)^.*/.SQLIT
1dff0 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1e000 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1e010 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51  t char*,...);.SQ
1e020 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1e030 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1e040 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1e050 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  list);.SQLITE_AP
1e060 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1e070 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1e080 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1e090 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ...);.SQLITE_API
1e0a0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
1e0b0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1e0c0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1e0d0 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
1e0e0 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1e0f0 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
1e100 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
1e110 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
1e120 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
1e130 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
1e140 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
1e150 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
1e160 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
1e170 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
1e180 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
1e190 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
1e1a0 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
1e1b0 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
1e1c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1e1d0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
1e1e0 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
1e1f0 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1e200 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
1e210 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
1e220 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1e230 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
1e240 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1e250 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
1e260 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
1e270 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
1e280 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
1e290 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1e2a0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
1e2b0 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
1e2c0 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
1e2d0 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
1e2e0 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
1e2f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1e300 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
1e310 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
1e320 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
1e330 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
1e340 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
1e350 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
1e360 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1e370 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1e380 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
1e390 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
1e3a0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
1e3b0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1e3c0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1e3d0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1e3e0 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
1e3f0 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
1e400 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
1e410 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1e420 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
1e430 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
1e440 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1e450 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1e460 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
1e470 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
1e480 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
1e490 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
1e4a0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
1e4b0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
1e4c0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
1e4d0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
1e4e0 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
1e4f0 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
1e500 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
1e510 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
1e520 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
1e530 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
1e540 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
1e550 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
1e560 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
1e570 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1e580 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
1e590 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
1e5a0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
1e5b0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
1e5c0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
1e5d0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
1e5e0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1e5f0 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1e600 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
1e610 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72   ^(The sqlite3_r
1e620 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
1e630 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
1e640 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
1e650 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1e660 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
1e670 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
1e680 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
1e690 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
1e6a0 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
1e6b0 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
1e6c0 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
1e6d0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e  .** parameter.)^
1e6e0 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20   ^ If the first 
1e6f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1e700 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
1e710 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
1e720 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
1e730 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
1e740 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
1e750 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1e760 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
1e770 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1e780 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1e790 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20  alloc()..** ^If 
1e7a0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1e7b0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1e7c0 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  realloc() is zer
1e7d0 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
1e7e0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1e7f0 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
1e800 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
1e810 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
1e820 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20  e(P) where P is 
1e830 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1e840 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1e850 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71  ealloc()..** ^sq
1e860 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1e870 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1e880 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
1e890 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
1e8a0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1e8b0 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
1e8c0 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
1e8d0 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
1e8e0 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73  ble..** ^If M is
1e8f0 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
1e900 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1e910 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
1e920 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
1e930 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1e940 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
1e950 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
1e960 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
1e970 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1e980 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74  _realloc() and t
1e990 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1e9a0 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1e9b0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1e9c0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e  lloc() returns N
1e9d0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ULL, then the pr
1e9e0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ior allocation.*
1e9f0 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  * is not freed..
1ea00 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1ea10 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
1ea20 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
1ea30 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
1ea40 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  oc().** is alway
1ea50 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
1ea60 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
1ea70 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
1ea80 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
1ea90 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
1eaa0 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
1eab0 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
1eac0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
1ead0 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
1eae0 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
1eaf0 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
1eb00 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
1eb10 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
1eb20 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
1eb30 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
1eb40 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
1eb50 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
1eb60 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
1eb70 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
1eb80 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
1eb90 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
1eba0 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
1ebb0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
1ebc0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
1ebd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
1ebe0 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
1ebf0 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20  .** The Windows 
1ec00 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
1ec10 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20  er calls.** the 
1ec20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
1ec30 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65 63  and free() direc
1ec40 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74  tly when convert
1ec50 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73  ing.** filenames
1ec60 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54 46   between the UTF
1ec70 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  -8 encoding used
1ec80 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e   by SQLite.** an
1ec90 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e  d whatever filen
1eca0 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ame encoding is 
1ecb0 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72 74  used by the part
1ecc0 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a  icular Windows.*
1ecd0 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20  * installation. 
1ece0 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   Memory allocati
1ecf0 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20 64 65  on errors are de
1ed00 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74  tected, but.** t
1ed10 68 65 79 20 61 72 65 20 72 65 70 6f 72 74 65 64  hey are reported
1ed20 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45   back as [SQLITE
1ed30 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a  _CANTOPEN] or.**
1ed40 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20   [SQLITE_IOERR] 
1ed50 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c  rather than [SQL
1ed60 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a  ITE_NOMEM]..**.*
1ed70 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72  * The pointer ar
1ed80 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69  guments to [sqli
1ed90 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20  te3_free()] and 
1eda0 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1edb0 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65  ()].** must be e
1edc0 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c  ither NULL or el
1edd0 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61  se pointers obta
1ede0 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f  ined from a prio
1edf0 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20  r.** invocation 
1ee00 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
1ee10 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  oc()] or [sqlite
1ee20 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61  3_realloc()] tha
1ee30 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65  t have.** not ye
1ee40 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e  t been released.
1ee50 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
1ee60 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  cation must not 
1ee70 72 65 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e  read or write an
1ee80 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62  y part of.** a b
1ee90 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61  lock of memory a
1eea0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
1eeb0 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a   released using.
1eec0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1eed0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1eee0 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 53  realloc()]..*/.S
1eef0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1ef00 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69  sqlite3_malloc(i
1ef10 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
1ef20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65  void *sqlite3_re
1ef30 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74  alloc(void*, int
1ef40 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1ef50 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  id sqlite3_free(
1ef60 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  void*);../*.** C
1ef70 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
1ef80 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69 73  Allocator Statis
1ef90 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  tics.**.** SQLit
1efa0 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73 65  e provides these
1efb0 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73 20   two interfaces 
1efc0 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e  for reporting on
1efd0 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f   the status.** o
1efe0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
1eff0 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74  alloc()], [sqlit
1f000 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64 20  e3_free()], and 
1f010 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1f020 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c  ()].** routines,
1f030 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65 20   which form the 
1f040 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20  built-in memory 
1f050 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
1f060 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  stem..**.** ^The
1f070 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1f080 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e 65  _used()] routine
1f090 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1f0a0 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20  ber of bytes.** 
1f0b0 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e  of memory curren
1f0c0 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67 20  tly outstanding 
1f0d0 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f  (malloced but no
1f0e0 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68  t freed)..** ^Th
1f0f0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
1f100 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 72  y_highwater()] r
1f110 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1f120 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61  he maximum.** va
1f130 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  lue of [sqlite3_
1f140 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 73  memory_used()] s
1f150 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77 61  ince the high-wa
1f160 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20  ter mark.** was 
1f170 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54 68  last reset.  ^Th
1f180 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
1f190 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d by [sqlite3_me
1f1a0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e 64  mory_used()] and
1f1b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1f1c0 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1f1d0 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76 65   include any ove
1f1e0 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20 62  rhead.** added b
1f1f0 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73 20  y SQLite in its 
1f200 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1f210 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  f [sqlite3_mallo
1f220 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74  c()],.** but not
1f230 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64 20   overhead added 
1f240 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65 72  by the any under
1f250 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69 62  lying system lib
1f260 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  rary.** routines
1f270 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d   that [sqlite3_m
1f280 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c  alloc()] may cal
1f290 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65  l..**.** ^The me
1f2a0 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72 20  mory high-water 
1f2b0 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74 6f  mark is reset to
1f2c0 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
1f2d0 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65  ue of.** [sqlite
1f2e0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1f2f0 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20   if and only if 
1f300 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  the parameter to
1f310 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  .** [sqlite3_mem
1f320 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
1f330 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65 20   is true.  ^The 
1f340 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a  value returned.*
1f350 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65  * by [sqlite3_me
1f360 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 31  mory_highwater(1
1f370 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d 77  )] is the high-w
1f380 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69  ater mark.** pri
1f390 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74 2e  or to the reset.
1f3a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73  .*/.SQLITE_API s
1f3b0 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c  qlite3_int64 sql
1f3c0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1f3d0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
1f3e0 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
1f3f0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1f400 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
1f410 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
1f420 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
1f430 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
1f440 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
1f450 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
1f460 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
1f470 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
1f480 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
1f490 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
1f4a0 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
1f4b0 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
1f4c0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
1f4d0 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
1f4e0 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
1f4f0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
1f500 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
1f510 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
1f520 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
1f530 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
1f540 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
1f550 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
1f560 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
1f570 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1f580 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
1f590 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
1f5a0 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
1f5b0 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
1f5c0 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
1f5d0 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
1f5e0 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
1f5f0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
1f600 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a 2a   buffer P..**.**
1f610 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65   ^The first time
1f620 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
1f630 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65 72   invoked (either
1f640 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20 62   internally or b
1f650 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  y.** the applica
1f660 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20 69  tion) the PRNG i
1f670 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  s seeded using r
1f680 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e  andomness obtain
1f690 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 78  ed.** from the x
1f6a0 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
1f6b0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
1f6c0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1f6d0 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c  bject..** ^On al
1f6e0 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e 76  l subsequent inv
1f6f0 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70 73  ocations, the ps
1f700 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20  eudo-randomness 
1f710 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20  is generated.** 
1f720 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77  internally and w
1f730 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65 20  ithout recourse 
1f740 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
1f750 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73  vfs] xRandomness
1f760 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 53  .** method..*/.S
1f770 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
1f780 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
1f790 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
1f7a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1f7b0 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
1f7c0 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
1f7d0 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1f7e0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
1f7f0 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
1f800 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
1f810 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
1f820 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1f830 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
1f840 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
1f850 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
1f860 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1f870 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1f880 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
1f890 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
1f8a0 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
1f8b0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1f8c0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
1f8d0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1f8e0 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
1f8f0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1f900 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1f910 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
1f920 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
1f930 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
1f940 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
1f950 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
1f960 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
1f970 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
1f980 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
1f990 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1f9a0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1f9b0 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
1f9c0 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
1f9d0 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
1f9e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1f9f0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
1fa00 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1fa10 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
1fa20 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
1fa30 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
1fa40 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
1fa50 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
1fa60 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
1fa70 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
1fa80 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
1fa90 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
1faa0 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
1fab0 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
1fac0 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
1fad0 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
1fae0 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
1faf0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1fb00 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1fb10 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1fb20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
1fb30 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
1fb40 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
1fb50 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
1fb60 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1fb70 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1fb80 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1fb90 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
1fba0 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1fbb0 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1fbc0 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
1fbd0 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
1fbe0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1fbf0 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
1fc00 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
1fc10 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
1fc20 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
1fc30 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1fc40 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
1fc50 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1fc60 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1fc70 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1fc80 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1fc90 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1fca0 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1fcb0 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1fcc0 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
1fcd0 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
1fce0 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
1fcf0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1fd00 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1fd10 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1fd20 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1fd30 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
1fd40 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
1fd50 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1fd60 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
1fd70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1fd80 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
1fd90 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1fda0 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
1fdb0 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
1fdc0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1fdd0 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
1fde0 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
1fdf0 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
1fe00 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1fe10 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
1fe20 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1fe30 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
1fe40 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1fe50 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
1fe60 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
1fe70 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1fe80 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1fe90 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1fea0 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1feb0 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
1fec0 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
1fed0 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1fee0 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1fef0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1ff00 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
1ff10 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
1ff20 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
1ff30 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
1ff40 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
1ff50 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1ff60 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
1ff70 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
1ff80 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
1ff90 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
1ffa0 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
1ffb0 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
1ffc0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
1ffd0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
1ffe0 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
1fff0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
20000 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
20010 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
20020 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
20030 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
20040 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
20050 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
20060 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
20070 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
20080 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
20090 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
200a0 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
200b0 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
200c0 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
200d0 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
200e0 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
200f0 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
20100 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
20110 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
20120 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
20130 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
20140 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
20150 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
20160 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
20170 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
20180 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
20190 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
201a0 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
201b0 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
201c0 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
201d0 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
201e0 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
201f0 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
20200 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
20210 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
20220 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
20230 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
20240 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
20250 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
20260 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
20270 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
20280 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
20290 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
202a0 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
202b0 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
202c0 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
202d0 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
202e0 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
202f0 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
20300 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
20310 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
20320 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
20330 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
20340 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
20350 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
20360 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
20370 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
20380 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
20390 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
203a0 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
203b0 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
203c0 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
203d0 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
203e0 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
203f0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
20400 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
20410 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
20420 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
20430 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
20440 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
20450 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
20460 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
20470 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
20480 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
20490 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
204a0 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
204b0 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
204c0 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
204d0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
204e0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
204f0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
20500 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
20510 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
20520 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
20530 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
20540 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
20550 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
20560 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
20570 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
20580 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20590 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
205a0 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
205b0 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
205c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
205d0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
205e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
205f0 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
20600 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
20610 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
20620 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
20630 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
20640 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
20650 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
20660 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
20670 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
20680 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
20690 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
206a0 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
206b0 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
206c0 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
206d0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
206e0 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
206f0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
20700 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
20710 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
20720 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
20730 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
20740 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
20750 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
20760 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
20770 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
20780 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
20790 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
207a0 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
207b0 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
207c0 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
207d0 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
207e0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
207f0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
20800 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
20810 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
20820 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
20830 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
20840 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
20850 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
20860 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
20870 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
20880 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
20890 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
208a0 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
208b0 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
208c0 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
208d0 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
208e0 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 53  ema change..*/.S
208f0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
20900 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
20910 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a  izer(.  sqlite3*
20920 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29  ,.  int (*xAuth)
20930 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
20940 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61   char*,const cha
20950 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63  r*,const char*,c
20960 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76  onst char*),.  v
20970 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29  oid *pUserData.)
20980 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
20990 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65  F: Authorizer Re
209a0 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  turn Codes.**.**
209b0 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   The [sqlite3_se
209c0 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
209d0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
209e0 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73  ck function] mus
209f0 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68  t.** return eith
20a00 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  er [SQLITE_OK] o
20a10 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74  r one of these t
20a20 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20  wo constants in 
20a30 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e  order.** to sign
20a40 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68 65  al SQLite whethe
20a50 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74  r or not the act
20a60 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64  ion is permitted
20a70 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73  .  See the.** [s
20a80 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
20a90 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
20aa0 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  er documentation
20ab0 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  ] for additional
20ac0 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
20ad0 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
20ae0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69   SQLITE_IGNORE i
20af0 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61  s also used as a
20b00 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
20b10 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d  K | return code]
20b20 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  .** from the [sq
20b30 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f  lite3_vtab_on_co
20b40 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66  nflict()] interf
20b50 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ace..*/.#define 
20b60 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20  SQLITE_DENY   1 
20b70 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53    /* Abort the S
20b80 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  QL statement wit
20b90 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64  h an error */.#d
20ba0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e  efine SQLITE_IGN
20bb0 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74  ORE 2   /* Don't
20bc0 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62   allow access, b
20bd0 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74  ut don't generat
20be0 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f  e an error */../
20bf0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
20c00 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e  uthorizer Action
20c10 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
20c20 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
20c30 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65  thorizer()] inte
20c40 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
20c50 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
20c60 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ion.** that is i
20c70 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72  nvoked to author
20c80 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20  ize certain SQL 
20c90 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e  statement action
20ca0 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  s.  The.** secon
20cb0 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
20cc0 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  he callback is a
20cd0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74  n integer code t
20ce0 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  hat specifies.**
20cf0 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20   what action is 
20d00 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64  being authorized
20d10 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68 65  .  These are the
20d20 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20   integer action 
20d30 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68  codes that.** th
20d40 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
20d50 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73  lback may be pas
20d60 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  sed..**.** These
20d70 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c   action code val
20d80 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61 74  ues signify what
20d90 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69   kind of operati
20da0 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61  on is to be.** a
20db0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20  uthorized.  The 
20dc0 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72 61  3rd and 4th para
20dd0 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61 75  meters to the au
20de0 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63  thorization.** c
20df0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20e00 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74   will be paramet
20e10 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65  ers or NULL depe
20e20 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f  nding on which o
20e30 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73  f these.** codes
20e40 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20   is used as the 
20e50 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
20e60 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61 72  .  ^(The 5th par
20e70 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a  ameter to the.**
20e80 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20e90 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65  back is the name
20ea0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
20eb0 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22   ("main", "temp"
20ec0 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70  ,.** etc.) if ap
20ed0 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68  plicable.)^  ^Th
20ee0 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 6th parameter 
20ef0 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
20f00 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  r callback.** is
20f10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
20f20 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67   inner-most trig
20f30 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61 74  ger or view that
20f40 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
20f50 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73  for.** the acces
20f60 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c  s attempt or NUL
20f70 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73 73  L if this access
20f80 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72 65   attempt is dire
20f90 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70  ctly from.** top
20fa0 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e  -level SQL code.
20fb0 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  .*/./***********
20fc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20fd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
20fe0 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   3rd ***********
20ff0 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 4th **********
21000 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21010 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20  E_CREATE_INDEX  
21020 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49          1   /* I
21030 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
21040 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
21050 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21060 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20  _CREATE_TABLE   
21070 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61         2   /* Ta
21080 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21090 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
210a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
210b0 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45  CREATE_TEMP_INDE
210c0 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64  X     3   /* Ind
210d0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
210e0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
210f0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21100 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45  REATE_TEMP_TABLE
21110 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c       4   /* Tabl
21120 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
21130 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
21140 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21150 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45  EATE_TEMP_TRIGGE
21160 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67  R   5   /* Trigg
21170 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
21180 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
21190 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
211a0 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ATE_TEMP_VIEW   
211b0 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e     6   /* View N
211c0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
211d0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
211e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
211f0 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  TE_TRIGGER      
21200 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72    7   /* Trigger
21210 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
21220 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21230 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21240 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  E_VIEW          
21250 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   8   /* View Nam
21260 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
21270 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21280 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45  ne SQLITE_DELETE
21290 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
212a0 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  9   /* Table Nam
212b0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
212c0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
212d0 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e  e SQLITE_DROP_IN
212e0 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31 30  DEX           10
212f0 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
21300 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
21310 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21320 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42   SQLITE_DROP_TAB
21330 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31 20  LE           11 
21340 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
21350 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21360 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21370 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
21380 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20 20  _INDEX      12  
21390 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
213a0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
213b0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
213c0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
213d0 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20 20  TABLE      13   
213e0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
213f0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
21400 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21410 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54  LITE_DROP_TEMP_T
21420 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20 2f  RIGGER    14   /
21430 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
21440 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21450 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21460 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49  ITE_DROP_TEMP_VI
21470 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a  EW       15   /*
21480 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
21490 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
214a0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
214b0 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20  TE_DROP_TRIGGER 
214c0 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20          16   /* 
214d0 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
214e0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
214f0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21500 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20  E_DROP_VIEW     
21510 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56         17   /* V
21520 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
21530 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21540 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21550 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20 20  _INSERT         
21560 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61        18   /* Ta
21570 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21580 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21590 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
215a0 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20 20  PRAGMA          
215b0 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61       19   /* Pra
215c0 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74  gma Name     1st
215d0 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a   arg or NULL */.
215e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
215f0 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20 20  EAD             
21600 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c      20   /* Tabl
21610 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
21620 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
21630 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45  define SQLITE_SE
21640 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 20  LECT            
21650 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     21   /* NULL 
21660 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
21670 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21680 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41  efine SQLITE_TRA
21690 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20  NSACTION        
216a0 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    22   /* Operat
216b0 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ion       NULL  
216c0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
216d0 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41  fine SQLITE_UPDA
216e0 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TE              
216f0 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   23   /* Table N
21700 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20  ame      Column 
21710 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66  Name     */.#def
21720 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43  ine SQLITE_ATTAC
21730 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
21740 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65  24   /* Filename
21750 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
21760 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21770 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48  ne SQLITE_DETACH
21780 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
21790 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
217a0 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20  Name   NULL     
217b0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
217c0 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54  e SQLITE_ALTER_T
217d0 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32 36  ABLE          26
217e0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e     /* Database N
217f0 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  ame   Table Name
21800 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21810 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20   SQLITE_REINDEX 
21820 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37 20               27 
21830 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
21840 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21850 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21860 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20  SQLITE_ANALYZE  
21870 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20 20              28  
21880 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
21890 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
218a0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
218b0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41  QLITE_CREATE_VTA
218c0 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20 20  BLE        29   
218d0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
218e0 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
218f0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21900 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45  LITE_DROP_VTABLE
21910 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20 2f            30   /
21920 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
21930 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20    Module Name   
21940 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21950 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  ITE_FUNCTION    
21960 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a           31   /*
21970 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21980 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20   Function Name  
21990 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
219a0 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20  TE_SAVEPOINT    
219b0 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20          32   /* 
219c0 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20  Operation       
219d0 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20  Savepoint Name  
219e0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
219f0 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20 20  E_COPY          
21a00 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e          0   /* N
21a10 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f  o longer used */
21a20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21a30 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50 72  : Tracing And Pr
21a40 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e  ofiling Function
21a50 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
21a60 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72 20  utines register 
21a70 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
21a80 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 75  ns that can be u
21a90 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69  sed for.** traci
21aa0 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67  ng and profiling
21ab0 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20 6f   the execution o
21ac0 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  f SQL statements
21ad0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
21ae0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
21af0 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
21b00 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73 20  ite3_trace() is 
21b10 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61  invoked at.** va
21b20 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65 6e  rious times when
21b30 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
21b40 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20 62  t is being run b
21b50 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  y [sqlite3_step(
21b60 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  )]..** ^The sqli
21b70 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c  te3_trace() call
21b80 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
21b90 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65 6e  with a UTF-8 ren
21ba0 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a  dering of the.**
21bb0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
21bc0 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74 65  ext as the state
21bd0 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69 6e  ment first begin
21be0 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20  s executing..** 
21bf0 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c  ^(Additional sql
21c00 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
21c10 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63 63  lbacks might occ
21c20 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74 72  ur.** as each tr
21c30 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67 72  iggered subprogr
21c40 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20 20  am is entered.  
21c50 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f  The callbacks fo
21c60 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f  r triggers.** co
21c70 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53 51  ntain a UTF-8 SQ
21c80 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69  L comment that i
21c90 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74 72  dentifies the tr
21ca0 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  igger.)^.**.** ^
21cb0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
21cc0 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64  ction registered
21cd0 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f 66   by sqlite3_prof
21ce0 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ile() is invoked
21cf0 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c 20  .** as each SQL 
21d00 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73 68  statement finish
21d10 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  es.  ^The profil
21d20 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
21d30 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69  ins.** the origi
21d40 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74 65  nal statement te
21d50 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d 61  xt and an estima
21d60 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63 6b  te of wall-clock
21d70 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77 20   time.** of how 
21d80 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65 6d  long that statem
21d90 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e 2e  ent took to run.
21da0 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63    ^The profile c
21db0 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65 20  allback.** time 
21dc0 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20 6e  is in units of n
21dd0 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77 65  anoseconds, howe
21de0 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  ver the current 
21df0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a 2a  implementation.*
21e00 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62 6c  * is only capabl
21e10 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  e of millisecond
21e20 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20 74   resolution so t
21e30 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69 67  he six least sig
21e40 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67 69  nificant.** digi
21e50 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20 61  ts in the time a
21e60 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e 20  re meaningless. 
21e70 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
21e80 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d 69   of SQLite.** mi
21e90 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65 61  ght provide grea
21ea0 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6f  ter resolution o
21eb0 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20 63  n the profiler c
21ec0 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a 2a  allback.  The.**
21ed0 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65   sqlite3_profile
21ee0 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63  () function is c
21ef0 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72 69  onsidered experi
21f00 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a 2a  mental and is.**
21f10 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e   subject to chan
21f20 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65 72  ge in future ver
21f30 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e  sions of SQLite.
21f40 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
21f50 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
21f60 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
21f70 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
21f80 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
21f90 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  oid*);.SQLITE_AP
21fa0 49 20 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  I SQLITE_EXPERIM
21fb0 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
21fc0 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
21fd0 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
21fe0 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
21ff0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
22000 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
22010 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
22020 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
22030 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
22040 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
22050 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
22060 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
22070 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
22080 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
22090 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
220a0 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
220b0 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
220c0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
220d0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
220e0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
220f0 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
22100 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
22110 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
22120 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
22130 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
22140 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
22150 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
22160 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
22170 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
22180 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
22190 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
221a0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
221b0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
221c0 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
221d0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
221e0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
221f0 20 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72   N is the number
22200 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c   of .** [virtual
22210 20 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63   machine instruc
22220 74 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20  tions] that are 
22230 65 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65  evaluated betwee
22240 6e 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20  n successive.** 
22250 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74  invocations of t
22260 68 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a  he callback X..*
22270 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e  *.** ^Only a sin
22280 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  gle progress han
22290 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69  dler may be defi
222a0 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20  ned at one time 
222b0 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  per.** [database
222c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65   connection]; se
222d0 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67  tting a new prog
222e0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e  ress handler can
222f0 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20  cels the.** old 
22300 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70  one.  ^Setting p
22310 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55  arameter X to NU
22320 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  LL disables the 
22330 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
22340 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65  ..** ^The progre
22350 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c  ss handler is al
22360 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73  so disabled by s
22370 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61  etting N to a va
22380 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e  lue less.** than
22390 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   1..**.** ^If th
223a0 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62  e progress callb
223b0 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ack returns non-
223c0 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74  zero, the operat
223d0 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72  ion is.** interr
223e0 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61  upted.  This fea
223f0 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64  ture can be used
22400 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a   to implement a.
22410 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74  ** "Cancel" butt
22420 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67  on on a GUI prog
22430 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e  ress dialog box.
22440 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72  .**.** The progr
22450 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  ess handler call
22460 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f  back must not do
22470 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77   anything that w
22480 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68  ill modify.** th
22490 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
224a0 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
224b0 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  ed the progress 
224c0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65  handler..** Note
224d0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
224e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
224f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
22500 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
22510 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
22520 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
22530 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
22540 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
22550 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f  paragraph..**.*/
22560 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
22570 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
22580 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
22590 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
225a0 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
225b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
225c0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
225d0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
225e0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
225f0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
22600 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
22610 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
22620 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
22630 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
22640 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
22650 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
22660 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
22670 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
22680 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
22690 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
226a0 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
226b0 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
226c0 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
226d0 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
226e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
226f0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
22700 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
22710 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
22720 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
22730 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
22740 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
22750 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
22760 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
22770 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
22780 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
22790 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
227a0 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
227b0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
227c0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
227d0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
227e0 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
227f0 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
22800 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
22810 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
22820 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
22830 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
22840 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
22850 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
22860 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
22870 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
22880 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
22890 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
228a0 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
228b0 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
228c0 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
228d0 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
228e0 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
228f0 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
22900 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
22910 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
22920 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
22930 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
22940 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
22950 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
22960 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
22970 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
22980 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
22990 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
229a0 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
229b0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
229c0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
229d0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
229e0 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
229f0 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
22a00 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
22a10 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
22a20 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
22a30 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
22a40 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
22a50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
22a60 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
22a70 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
22a80 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
22a90 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
22aa0 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
22ab0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
22ac0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
22ad0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
22ae0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
22af0 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
22b00 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
22b10 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
22b20 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
22b30 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
22b40 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
22b50 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
22b60 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
22b70 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
22b80 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
22b90 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
22ba0 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
22bb0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
22bc0 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
22bd0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
22be0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
22bf0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
22c00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
22c10 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
22c20 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
22c30 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
22c40 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
22c50 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
22c60 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
22c70 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
22c80 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
22c90 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
22ca0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
22cb0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
22cc0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
22cd0 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
22ce0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
22cf0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
22d00 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
22d10 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
22d20 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
22d30 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
22d40 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
22d50 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
22d60 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
22d70 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
22d80 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
22d90 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
22da0 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
22db0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
22dc0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
22dd0 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
22de0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
22df0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
22e00 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
22e10 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
22e20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
22e30 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
22e40 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
22e50 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
22e60 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
22e70 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
22e80 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
22e90 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
22ea0 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
22eb0 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
22ec0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
22ed0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
22ee0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
22ef0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
22f00 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
22f10 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
22f20 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
22f30 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
22f40 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
22f50 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
22f60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
22f70 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
22f80 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
22f90 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
22fa0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
22fb0 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
22fc0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
22fd0 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
22fe0 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
22ff0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
23000 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
23010 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
23020 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
23030 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
23040 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
23050 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
23060 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
23070 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
23080 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
23090 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
230a0 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
230b0 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
230c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
230d0 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
230e0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
230f0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
23100 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
23110 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
23120 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
23130 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
23140 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
23150 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
23160 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
23170 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
23180 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
23190 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
231a0 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
231b0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
231c0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
231d0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
231e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
231f0 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
23200 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
23210 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
23220 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
23230 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
23240 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
23250 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
23260 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
23270 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
23280 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
23290 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
232a0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
232b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
232c0 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
232d0 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
232e0 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
232f0 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
23300 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
23310 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
23320 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
23330 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
23340 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
23350 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
23360 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
23370 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
23380 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
23390 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
233a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
233b0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
233c0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
233d0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
233e0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
233f0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
23400 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
23410 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
23420 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
23430 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
23440 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
23450 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
23460 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
23470 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
23480 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
23490 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
234a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
234b0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
234c0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
234d0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
234e0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
234f0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
23500 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
23510 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
23520 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
23530 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
23540 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
23550 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
23560 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
23570 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
23580 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
23590 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
235a0 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
235b0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
235c0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
235d0 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
235e0 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
235f0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
23600 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
23610 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
23620 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
23630 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
23640 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
23650 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
23660 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
23670 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
23680 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
23690 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
236a0 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
236b0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
236c0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
236d0 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
236e0 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
236f0 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
23700 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
23710 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
23720 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
23730 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
23740 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
23750 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
23760 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
23770 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
23780 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
23790 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
237a0 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
237b0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
237c0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
237d0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
237e0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
237f0 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20 66  .** set in the f
23800 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74  ourth argument t
23810 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
23820 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68 61  2(), or if it ha
23830 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c 65  s.** been enable
23840 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e 67  d globally using
23850 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   the [SQLITE_CON
23860 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e 20  FIG_URI] option 
23870 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  with the.** [sql
23880 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 6d  ite3_config()] m
23890 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65 20  ethod or by the 
238a0 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
238b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
238c0 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20 53  tion..** As of S
238d0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
238e0 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61 6d  7.7, URI filenam
238f0 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  e interpretation
23900 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a 2a   is turned off.*
23910 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62 75  * by default, bu
23920 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65  t future release
23930 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
23940 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69 6c  t enable URI fil
23950 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70 72  ename.** interpr
23960 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61 75  etation by defau
23970 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20 66  lt.  See "[URI f
23980 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20 61  ilenames]" for a
23990 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
239a0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
239b0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  URI filenames ar
239c0 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64 69  e parsed accordi
239d0 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e 20  ng to RFC 3986. 
239e0 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e 74  ^If the URI cont
239f0 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68 6f  ains an.** autho
23a00 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d 75  rity, then it mu
23a10 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e 20  st be either an 
23a20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20  empty string or 
23a30 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20 22  the string .** "
23a40 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66 20  localhost". ^If 
23a50 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69 73  the authority is
23a60 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73 74   not an empty st
23a70 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68 6f  ring or "localho
23a80 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72 6f  st", an .** erro
23a90 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74 6f  r is returned to
23aa0 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54 68   the caller. ^Th
23ab0 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70 6f  e fragment compo
23ac0 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20 69  nent of a URI, i
23ad0 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20 69  f .** present, i
23ae0 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a  s ignored..**.**
23af0 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68   ^SQLite uses th
23b00 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e 74  e path component
23b10 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74   of the URI as t
23b20 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64  he name of the d
23b30 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69 63  isk file.** whic
23b40 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 64  h contains the d
23b50 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68 65  atabase. ^If the
23b60 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74   path begins wit
23b70 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65  h a '/' characte
23b80 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  r, .** then it i
23b90 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
23ba0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
23bb0 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  h. ^If the path 
23bc0 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20 0a  does not begin .
23bd0 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28 6d  ** with a '/' (m
23be0 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65 20  eaning that the 
23bf0 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69 6f  authority sectio
23c00 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  n is omitted fro
23c10 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74 68  m the URI).** th
23c20 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20 69  en the path is i
23c30 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
23c40 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20 0a  relative path. .
23c50 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c 20  ** ^On windows, 
23c60 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f 6e  the first compon
23c70 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c 75  ent of an absolu
23c80 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20 61  te path .** is a
23c90 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63 61   drive specifica
23ca0 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22 29  tion (e.g. "C:")
23cb0 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20 55  ..**.** [[core U
23cc0 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  RI query paramet
23cd0 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75 65  ers]].** The que
23ce0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  ry component of 
23cf0 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61 69  a URI may contai
23d00 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
23d10 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  t are interprete
23d20 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20 53  d.** either by S
23d30 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f 72  QLite itself, or
23d40 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75 73   by a [VFS | cus
23d50 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  tom VFS implemen
23d60 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c 69  tation]..** SQLi
23d70 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  te interprets th
23d80 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65  e following thre
23d90 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
23da0 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  rs:.**.** <ul>.*
23db0 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73 3c  *   <li> <b>vfs<
23dc0 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22 20  /b>: ^The "vfs" 
23dd0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
23de0 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66 79   used to specify
23df0 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a 20   the name of.** 
23e00 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63 74      a VFS object
23e10 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20 74   that provides t
23e20 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
23e30 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68  tem interface th
23e40 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20 20  at should.**    
23e50 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63 65   be used to acce
23e60 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
23e70 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e 49  file on disk. ^I
23e80 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69 73  f this option is
23e90 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20 61   set to.**     a
23ea0 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 74  n empty string t
23eb0 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20 6f  he default VFS o
23ec0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20 5e  bject is used. ^
23ed0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
23ee0 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46 53  known.**     VFS
23ef0 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e 49   is an error. ^I
23f00 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
23f10 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
23f20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20 69  the vfs option i
23f30 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e 74  s.**     present
23f40 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 73  , then the VFS s
23f50 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
23f60 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72 65  option takes pre
23f70 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a 20  cedence over.** 
23f80 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70 61      the value pa
23f90 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
23fa0 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
23fb0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
23fc0 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  )..**.**   <li> 
23fd0 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28 54  <b>mode</b>: ^(T
23fe0 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
23ff0 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20  r may be set to 
24000 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72 77  either "ro", "rw
24010 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 72 77 63  " or.**     "rwc
24020 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f  ". Attempting to
24030 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f   set it to any o
24040 74 68 65 72 20 76 61 6c 75 65 20 69 73 20 61 6e  ther value is an
24050 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20   error)^. .**   
24060 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73 70    ^If "ro" is sp
24070 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74 68  ecified, then th
24080 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
24090 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f 6e  ened for read-on
240a0 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73  ly .**     acces
240b0 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74 68  s, just as if th
240c0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  e [SQLITE_OPEN_R
240d0 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68 61  EADONLY] flag ha
240e0 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74 68  d been set in th
240f0 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64 20  e .**     third 
24100 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
24110 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
24120 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
24130 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
24140 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
24150 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
24160 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
24170 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
24180 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
24190 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
241a0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
241b0 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
241c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
241d0 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
241e0 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
241f0 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
24200 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
24210 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
24220 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
24230 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
24240 4e 5f 43 52 45 41 54 45 2e 20 5e 49 66 20 73 71  N_CREATE. ^If sq
24250 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24260 69 73 20 0a 2a 2a 20 20 20 20 20 75 73 65 64 2c  is .**     used,
24270 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
24280 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c  to specify a val
24290 75 65 20 66 6f 72 20 74 68 65 20 6d 6f 64 65 20  ue for the mode 
242a0 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20 69  parameter that i
242b0 73 20 0a 2a 2a 20 20 20 20 20 6c 65 73 73 20 72  s .**     less r
242c0 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
242d0 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
242e0 79 20 74 68 65 20 66 6c 61 67 73 20 70 61 73 73  y the flags pass
242f0 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64 20  ed as the third 
24300 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65  .**     paramete
24310 72 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20  r..**.**   <li> 
24320 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54  <b>cache</b>: ^T
24330 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
24340 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
24350 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64 22   either "shared"
24360 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76   or.**     "priv
24370 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69  ate". ^Setting i
24380 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69 73  t to "shared" is
24390 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
243a0 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20  etting the.**   
243b0 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48    SQLITE_OPEN_SH
243c0 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69 6e  AREDCACHE bit in
243d0 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   the flags argum
243e0 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a  ent passed to.**
243f0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65       sqlite3_ope
24400 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67  n_v2(). ^Setting
24410 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61 6d   the cache param
24420 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74 65  eter to "private
24430 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75  " is .**     equ
24440 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69  ivalent to setti
24450 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50  ng the SQLITE_OP
24460 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
24470 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20  bit..**     ^If 
24480 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
24490 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74 68  ) is used and th
244a0 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d 65  e "cache" parame
244b0 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20 69  ter is present i
244c0 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66  n.**     a URI f
244d0 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c  ilename, its val
244e0 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79  ue overrides any
244f0 20 62 65 68 61 76 69 6f 75 72 20 72 65 71 75 65   behaviour reque
24500 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a  sted by setting.
24510 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50  **     SQLITE_OP
24520 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
24530 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  or SQLITE_OPEN_S
24540 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e  HAREDCACHE flag.
24550 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
24560 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
24570 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72  nknown parameter
24580 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f   in the query co
24590 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
245a0 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72   is not an.** er
245b0 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72  ror.  Future ver
245c0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
245d0 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64  might understand
245e0 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72   additional quer
245f0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  y.** parameters.
24600 20 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61    See "[query pa
24610 72 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70  rameters with sp
24620 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f  ecial meaning to
24630 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a   SQLite]" for.**
24640 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
24650 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b  rmation..**.** [
24660 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  [URI filename ex
24670 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49  amples]] <h3>URI
24680 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c   filename exampl
24690 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74  es</h3>.**.** <t
246a0 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20  able border="1" 
246b0 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c  align=center cel
246c0 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c  lpadding=5>.** <
246d0 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65  tr><th> URI file
246e0 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c  names <th> Resul
246f0 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  ts.** <tr><td> f
24700 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e  ile:data.db <td>
24710 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
24720 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
24730 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72  a.db" in the cur
24740 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a  rent directory..
24750 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
24760 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  :/home/fred/data
24770 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20  .db<br>.**      
24780 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65      file:///home
24790 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
247a0 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  r> .**          
247b0 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74  file://localhost
247c0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
247d0 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a  db <br> <td> .**
247e0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74            Open t
247f0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
24800 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
24810 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  a.db"..** <tr><t
24820 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74  d> file://darkst
24830 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  ar/home/fred/dat
24840 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  a.db <td> .**   
24850 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
24860 20 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e   "darkstar" is n
24870 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20  ot a recognized 
24880 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74  authority..** <t
24890 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69  r><td style="whi
248a0 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22  te-space:nowrap"
248b0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
248c0 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65  ile:///C:/Docume
248d0 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74  nts%20and%20Sett
248e0 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f  ings/fred/Deskto
248f0 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20  p/data.db.**    
24900 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e   <td> Windows on
24910 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c  ly: Open the fil
24920 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66  e "data.db" on f
24930 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e  red's desktop on
24940 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20   drive.**       
24950 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74     C:. Note that
24960 20 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e   the %20 escapin
24970 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c  g in this exampl
24980 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c  e is not strictl
24990 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e  y .**          n
249a0 65 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65  ecessary - space
249b0 20 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20   characters can 
249c0 62 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c  be used literall
249d0 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e  y.**          in
249e0 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a   URI filenames..
249f0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
24a00 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f  :data.db?mode=ro
24a10 26 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c  &cache=private <
24a20 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
24a30 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61   Open file "data
24a40 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
24a50 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f  ent directory fo
24a60 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65  r read-only acce
24a70 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ss..**          
24a80 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
24a90 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61  ether or not sha
24aa0 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69  red-cache mode i
24ab0 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20  s enabled by.** 
24ac0 20 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74           default
24ad0 2c 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20  , use a private 
24ae0 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74  cache..** <tr><t
24af0 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72  d> file:/home/fr
24b00 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75  ed/data.db?vfs=u
24b10 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a  nix-nolock <td>.
24b20 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
24b30 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
24b40 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
24b50 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
24b60 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a  "unix-nolock"..*
24b70 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
24b80 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61  data.db?mode=rea
24b90 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20  donly <td> .**  
24ba0 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72          An error
24bb0 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20  . "readonly" is 
24bc0 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69  not a valid opti
24bd0 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65  on for the "mode
24be0 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20  " parameter..** 
24bf0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e  </table>.**.** ^
24c00 55 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20  URI hexadecimal 
24c10 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
24c20 20 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f   (%HH) are suppo
24c30 72 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20  rted within the 
24c40 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72  path and.** quer
24c50 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20  y components of 
24c60 61 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63  a URI. A hexadec
24c70 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
24c80 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66  ence consists of
24c90 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69   a.** percent si
24ca0 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f  gn - "%" - follo
24cb0 77 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74  wed by exactly t
24cc0 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64  wo hexadecimal d
24cd0 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66  igits .** specif
24ce0 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61  ying an octet va
24cf0 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65  lue. ^Before the
24d00 20 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63   path or query c
24d10 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a  omponents of a.*
24d20 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61  * URI filename a
24d30 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20  re interpreted, 
24d40 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64  they are encoded
24d50 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64   using UTF-8 and
24d60 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63   all .** hexadec
24d70 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75  imal escape sequ
24d80 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62  ences replaced b
24d90 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20  y a single byte 
24da0 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a  containing the.*
24db0 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  * corresponding 
24dc0 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70  octet. If this p
24dd0 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73  rocess generates
24de0 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d   an invalid UTF-
24df0 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74  8 encoding,.** t
24e00 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
24e10 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
24e20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f  <b>Note to Windo
24e30 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54  ws users:</b>  T
24e40 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64  he encoding used
24e50 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d   for the filenam
24e60 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66  e argument.** of
24e70 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
24e80 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
24e90 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54  _v2() must be UT
24ea0 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65  F-8, not whateve
24eb0 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73  r.** codepage is
24ec0 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
24ed0 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63  ed.  Filenames c
24ee0 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e  ontaining intern
24ef0 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61  ational.** chara
24f00 63 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f  cters must be co
24f10 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38  nverted to UTF-8
24f20 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e   prior to passin
24f30 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73  g them into.** s
24f40 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72  qlite3_open() or
24f50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24f60 28 29 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ()..*/.SQLITE_AP
24f70 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
24f80 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
24f90 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
24fa0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
24fb0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
24fc0 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
24fd0 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
24fe0 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
24ff0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
25000 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  I int sqlite3_op
25010 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f  en16(.  const vo
25020 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20  id *filename,   
25030 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65  /* Database file
25040 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f  name (UTF-16) */
25050 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44  .  sqlite3 **ppD
25060 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55  b          /* OU
25070 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e  T: SQLite db han
25080 64 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  dle */.);.SQLITE
25090 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
250a0 5f 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73  _open_v2(.  cons
250b0 74 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65  t char *filename
250c0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
250d0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29  filename (UTF-8)
250e0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
250f0 70 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a  ppDb,         /*
25100 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
25110 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  handle */.  int 
25120 66 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20  flags,          
25130 20 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a      /* Flags */.
25140 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56    const char *zV
25150 66 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d  fs        /* Nam
25160 65 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20  e of VFS module 
25170 74 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a  to use */.);../*
25180 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62  .** CAPI3REF: Ob
25190 74 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20  tain Values For 
251a0 55 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a  URI Parameters.*
251b0 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75  *.** These are u
251c0 74 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c  tility routines,
251d0 20 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69   useful to VFS i
251e0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20  mplementations, 
251f0 74 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f  that check.** to
25200 20 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61   see if a databa
25210 73 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52  se file was a UR
25220 49 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64  I that contained
25230 20 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72   a specific quer
25240 79 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c  y .** parameter,
25250 20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69   and if so obtai
25260 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
25270 74 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d  that query param
25280 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46  eter..**.** If F
25290 20 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65   is the database
252a0 20 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65   filename pointe
252b0 72 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  r passed into th
252c0 65 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64  e xOpen() method
252d0 20 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d   of .** a VFS im
252e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65  plementation whe
252f0 6e 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61  n the flags para
25300 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29  meter to xOpen()
25310 20 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20   has one or .** 
25320 6d 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c  more of the [SQL
25330 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72  ITE_OPEN_URI] or
25340 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
25350 49 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20  IN_DB] bits set 
25360 61 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20  and.** P is the 
25370 6e 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72  name of the quer
25380 79 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  y parameter, the
25390 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  n.** sqlite3_uri
253a0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
253b0 72 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75  returns the valu
253c0 65 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61  e of the P.** pa
253d0 72 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78  rameter if it ex
253e0 69 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70  ists or a NULL p
253f0 6f 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73  ointer if P does
25400 20 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61   not appear as a
25410 20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d   .** query param
25420 65 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50  eter on F.  If P
25430 20 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61   is a query para
25440 6d 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61  meter of F.** ha
25450 73 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61  s no explicit va
25460 6c 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  lue, then sqlite
25470 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
25480 46 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20  F,P) returns.** 
25490 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  a pointer to an 
254a0 65 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a  empty string..**
254b0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
254c0 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c  uri_boolean(F,P,
254d0 42 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d  B) routine assum
254e0 65 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62  es that P is a b
254f0 6f 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65  oolean.** parame
25500 74 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ter and returns 
25510 74 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73  true (1) or fals
25520 65 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20  e (0) according 
25530 74 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20  to the value.** 
25540 6f 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74  of P.  The sqlit
25550 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
25560 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65  ,P,B) routine re
25570 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69  turns true (1) i
25580 66 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  f the.** value o
25590 66 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  f query paramete
255a0 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79  r P is one of "y
255b0 65 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20  es", "true", or 
255c0 22 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63  "on" in any.** c
255d0 61 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61  ase or if the va
255e0 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20  lue begins with 
255f0 61 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65  a non-zero numbe
25600 72 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69  r.  The .** sqli
25610 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
25620 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20  F,P,B) routines 
25630 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30  returns false (0
25640 29 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f  ) if the value o
25650 66 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d  f.** query param
25660 65 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66  eter P is one of
25670 20 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20   "no", "false", 
25680 6f 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20  or "off" in any 
25690 63 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68  case or.** if th
256a0 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77  e value begins w
256b0 69 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65  ith a numeric ze
256c0 72 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74  ro.  If P is not
256d0 20 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61   a query.** para
256e0 6d 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66  meter on F or if
256f0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
25700 69 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63  is does not matc
25710 68 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20  h any of the.** 
25720 61 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69  above, then sqli
25730 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
25740 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28  F,P,B) returns (
25750 42 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  B!=0)..**.** The
25760 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
25770 36 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e  64(F,P,D) routin
25780 65 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76  e converts the v
25790 61 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61  alue of P into a
257a0 0a 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65  .** 64-bit signe
257b0 64 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65  d integer and re
257c0 74 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67  turns that integ
257d0 65 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f  er, or D if P do
257e0 65 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e  es not.** exist.
257f0 20 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f    If the value o
25800 66 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67  f P is something
25810 20 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69   other than an i
25820 6e 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  nteger, then.** 
25830 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
25840 2e 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73  ..** .** If F is
25850 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
25860 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72   then sqlite3_ur
25870 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29  i_parameter(F,P)
25880 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e   returns NULL an
25890 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69  d.** sqlite3_uri
258a0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
258b0 72 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46  returns B.  If F
258c0 20 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70   is not a NULL p
258d0 6f 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73  ointer and.** is
258e0 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20   not a database 
258f0 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f  file pathname po
25900 69 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74  inter that SQLit
25910 65 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68  e passed into th
25920 65 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d  e xOpen.** VFS m
25930 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20  ethod, then the 
25940 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73  behavior of this
25950 20 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65   routine is unde
25960 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
25970 6c 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  ly.** undesirabl
25980 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  e..*/.SQLITE_API
25990 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c   const char *sql
259a0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
259b0 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
259c0 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
259d0 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53  char *zParam);.S
259e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
259f0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
25a00 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
25a10 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
25a20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
25a30 66 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41  fault);.SQLITE_A
25a40 50 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  PI sqlite3_int64
25a50 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74   sqlite3_uri_int
25a60 36 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  64(const char*, 
25a70 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c  const char*, sql
25a80 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f  ite3_int64);.../
25a90 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
25aa0 72 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d  rror Codes And M
25ab0 65 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54  essages.**.** ^T
25ac0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  he sqlite3_errco
25ad0 64 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  de() interface r
25ae0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72  eturns the numer
25af0 69 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  ic [result code]
25b00 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
25b10 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f   result code] fo
25b20 72 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  r the most recen
25b30 74 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33  t failed sqlite3
25b40 5f 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61  _* API call.** a
25b50 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61  ssociated with a
25b60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
25b70 63 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69  ction]. If a pri
25b80 6f 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c  or API call fail
25b90 65 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f  ed.** but the mo
25ba0 73 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61  st recent API ca
25bb0 6c 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68  ll succeeded, th
25bc0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
25bd0 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  rom.** sqlite3_e
25be0 72 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65  rrcode() is unde
25bf0 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  fined.  ^The sql
25c00 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72  ite3_extended_er
25c10 72 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72  rcode().** inter
25c20 66 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65  face is the same
25c30 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
25c40 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74  always returns t
25c50 68 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64  he .** [extended
25c60 20 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76   result code] ev
25c70 65 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64  en when extended
25c80 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
25c90 65 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a  e.** disabled..*
25ca0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
25cb0 33 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73  3_errmsg() and s
25cc0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
25cd0 29 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68  ) return English
25ce0 2d 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78  -language.** tex
25cf0 74 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73  t that describes
25d00 20 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65   the error, as e
25d10 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55  ither UTF-8 or U
25d20 54 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65  TF-16 respective
25d30 6c 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20  ly..** ^(Memory 
25d40 74 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f  to hold the erro
25d50 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  r message string
25d60 20 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65   is managed inte
25d70 72 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61  rnally..** The a
25d80 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20  pplication does 
25d90 6e 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72  not need to worr
25da0 79 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20  y about freeing 
25db0 74 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48  the result..** H
25dc0 6f 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f  owever, the erro
25dd0 72 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62  r string might b
25de0 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72  e overwritten or
25df0 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a   deallocated by.
25e00 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ** subsequent ca
25e10 6c 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c  lls to other SQL
25e20 69 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75  ite interface fu
25e30 6e 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a  nctions.)^.**.**
25e40 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
25e50 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
25e60 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
25e70 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
25e80 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
25e90 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
25ea0 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
25eb0 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
25ec0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
25ed0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
25ee0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
25ef0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
25f00 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
25f10 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
25f20 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
25f30 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
25f40 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
25f50 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
25f60 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
25f70 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
25f80 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
25f90 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
25fa0 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
25fb0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
25fc0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
25fd0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
25fe0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
25ff0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
26000 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
26010 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
26020 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
26030 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
26040 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
26050 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
26060 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
26070 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
26080 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
26090 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
260a0 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
260b0 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
260c0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
260d0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
260e0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
260f0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
26100 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
26110 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
26120 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
26130 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
26140 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
26150 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
26160 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  t..*/.SQLITE_API
26170 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72   int sqlite3_err
26180 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
26190 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
261a0 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  t sqlite3_extend
261b0 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74  ed_errcode(sqlit
261c0 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f  e3 *db);.SQLITE_
261d0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
261e0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73  sqlite3_errmsg(s
261f0 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45  qlite3*);.SQLITE
26200 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
26210 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  *sqlite3_errmsg1
26220 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  6(sqlite3*);../*
26230 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
26240 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  L Statement Obje
26250 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ct.** KEYWORDS: 
26260 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  {prepared statem
26270 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73  ent} {prepared s
26280 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a  tatements}.**.**
26290 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
262a0 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72  this object repr
262b0 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20  esents a single 
262c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a  SQL statement..*
262d0 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
262e0 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e   variously known
262f0 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64 20   as a "prepared 
26300 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a  statement" or a.
26310 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c  ** "compiled SQL
26320 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73   statement" or s
26330 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61 74  imply as a "stat
26340 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  ement"..**.** Th
26350 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74  e life of a stat
26360 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65  ement object goe
26370 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65  s something like
26380 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   this:.**.** <ol
26390 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65  >.** <li> Create
263a0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
263b0 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
263c0 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65  re_v2()] or a re
263d0 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75  lated.**      fu
263e0 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20  nction..** <li> 
263f0 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b  Bind values to [
26400 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d  host parameters]
26410 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74   using the sqlit
26420 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20  e3_bind_*().**  
26430 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a      interfaces..
26440 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20  ** <li> Run the 
26450 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b  SQL by calling [
26460 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
26470 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65  one or more time
26480 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74  s..** <li> Reset
26490 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75   the statement u
264a0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
264b0 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62  set()] then go b
264c0 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73  ack.**      to s
264d0 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20  tep 2.  Do this 
264e0 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d  zero or more tim
264f0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74  es..** <li> Dest
26500 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75  roy the object u
26510 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
26520 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f  nalize()]..** </
26530 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20  ol>.**.** Refer 
26540 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  to documentation
26550 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d   on individual m
26560 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72  ethods above for
26570 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
26580 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74  nformation..*/.t
26590 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
265a0 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74  lite3_stmt sqlit
265b0 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20  e3_stmt;../*.** 
265c0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69  CAPI3REF: Run-ti
265d0 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20  me Limits.**.** 
265e0 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  ^(This interface
265f0 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65   allows the size
26600 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73   of various cons
26610 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d  tructs to be lim
26620 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e  ited.** on a con
26630 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65  nection by conne
26640 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68  ction basis.  Th
26650 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
26660 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74  r is the.** [dat
26670 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
26680 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73  ] whose limit is
26690 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75   to be set or qu
266a0 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73  eried.  The.** s
266b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
266c0 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c  is one of the [l
266d0 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d  imit categories]
266e0 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a   that define a.*
266f0 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74  * class of const
26700 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65  ructs to be size
26710 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74   limited.  The t
26720 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 69  hird parameter i
26730 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d  s the.** new lim
26740 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73  it for that cons
26750 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  truct.)^.**.** ^
26760 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74  If the new limit
26770 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e   is a negative n
26780 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74  umber, the limit
26790 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a   is unchanged..*
267a0 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d  * ^(For each lim
267b0 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49  it category SQLI
267c0 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45  TE_LIMIT_<i>NAME
267d0 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61 20  </i> there is a 
267e0 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61  .** [limits | ha
267f0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a  rd upper bound].
26800 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  ** set at compil
26810 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70 72  e-time by a C pr
26820 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  eprocessor macro
26830 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69   called.** [limi
26840 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ts | SQLITE_MAX_
26850 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a  <i>NAME</i>]..**
26860 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20   (The "_LIMIT_" 
26870 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63  in the name is c
26880 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f  hanged to "_MAX_
26890 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70  ".))^.** ^Attemp
268a0 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61  ts to increase a
268b0 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73   limit above its
268c0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
268d0 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c  d are.** silentl
268e0 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74  y truncated to t
268f0 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62 6f  he hard upper bo
26900 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61  und..**.** ^Rega
26910 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
26920 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d  r or not the lim
26930 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20  it was changed, 
26940 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  the .** [sqlite3
26950 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66  _limit()] interf
26960 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
26970 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74  prior value of t
26980 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65  he limit..** ^He
26990 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65  nce, to find the
269a0 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
269b0 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75  f a limit withou
269c0 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a  t changing it,.*
269d0 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20  * simply invoke 
269e0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 77  this interface w
269f0 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70 61  ith the third pa
26a00 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d  rameter set to -
26a10 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d  1..**.** Run-tim
26a20 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74  e limits are int
26a30 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
26a40 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68   applications th
26a50 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74  at manage.** bot
26a60 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65  h their own inte
26a70 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e  rnal database an
26a80 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73  d also databases
26a90 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f   that are contro
26aa0 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75  lled.** by untru
26ab0 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f  sted external so
26ac0 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70  urces.  An examp
26ad0 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  le application m
26ae0 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62  ight be a.** web
26af0 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68 61   browser that ha
26b00 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61  s its own databa
26b10 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ses for storing 
26b20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73  history and.** s
26b30 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73 65  eparate database
26b40 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
26b50 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c 69  JavaScript appli
26b60 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64  cations download
26b70 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e  ed.** off the In
26b80 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74  ternet.  The int
26b90 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20  ernal databases 
26ba0 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65  can be given the
26bb0 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75  .** large, defau
26bc0 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61  lt limits.  Data
26bd0 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79  bases managed by
26be0 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
26bf0 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65  s can.** be give
26c00 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c  n much smaller l
26c10 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20 74  imits designed t
26c20 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69  o prevent a deni
26c30 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a  al of service.**
26c40 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f   attack.  Develo
26c50 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20  pers might also 
26c60 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20  want to use the 
26c70 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
26c80 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e  horizer()].** in
26c90 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74 68  terface to furth
26ca0 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75  er control untru
26cb0 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73  sted SQL.  The s
26cc0 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ize of the datab
26cd0 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62  ase.** created b
26ce0 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73  y an untrusted s
26cf0 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e  cript can be con
26d00 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65  tained using the
26d10 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f  .** [max_page_co
26d20 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a  unt] [PRAGMA]..*
26d30 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d  *.** New run-tim
26d40 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  e limit categori
26d50 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20  es may be added 
26d60 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  in future releas
26d70 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  es..*/.SQLITE_AP
26d80 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69  I int sqlite3_li
26d90 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  mit(sqlite3*, in
26da0 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c  t id, int newVal
26db0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26dc0 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d  EF: Run-Time Lim
26dd0 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a  it Categories.**
26de0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69   KEYWORDS: {limi
26df0 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69  t category} {*li
26e00 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a  mit categories}.
26e10 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
26e20 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72  tants define var
26e30 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65  ious performance
26e40 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20   limits.** that 
26e50 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61  can be lowered a
26e60 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67  t run-time using
26e70 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
26e80 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70  )]..** The synop
26e90 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69  sis of the meani
26ea0 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f  ngs of the vario
26eb0 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f  us limits is sho
26ec0 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64  wn below..** Add
26ed0 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
26ee0 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65  ion is available
26ef0 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69   at [limits | Li
26f00 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e  mits in SQLite].
26f10 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b  .**.** <dl>.** [
26f20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  [SQLITE_LIMIT_LE
26f30 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  NGTH]] ^(<dt>SQL
26f40 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
26f50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
26f60 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66   maximum size of
26f70 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42   any string or B
26f80 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77  LOB or table row
26f90 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29  , in bytes.<dd>)
26fa0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
26fb0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
26fc0 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
26fd0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
26fe0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
26ff0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
27000 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65   of an SQL state
27010 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c  ment, in bytes.<
27020 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
27030 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
27040 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  MN]] ^(<dt>SQLIT
27050 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f  E_LIMIT_COLUMN</
27060 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
27070 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
27080 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61   columns in a ta
27090 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f  ble definition o
270a0 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75  r in the.** resu
270b0 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
270c0 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69  ECT] or the maxi
270d0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
270e0 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65  lumns in an inde
270f0 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52  x.** or in an OR
27100 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20  DER BY or GROUP 
27110 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29  BY clause.</dd>)
27120 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
27130 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
27140 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
27150 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54  _LIMIT_EXPR_DEPT
27160 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
27170 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
27180 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72 65  of the parse tre
27190 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73  e on any express
271a0 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ion.</dd>)^.**.*
271b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
271c0 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
271d0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
271e0 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53  LIMIT_COMPOUND_S
271f0 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ELECT</dt>.** <d
27200 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
27210 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e  mber of terms in
27220 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45   a compound SELE
27230 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64  CT statement.</d
27240 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
27250 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f  ITE_LIMIT_VDBE_O
27260 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  P]] ^(<dt>SQLITE
27270 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
27280 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
27290 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
272a0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
272b0 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
272c0 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
272d0 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
272e0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
272f0 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73  .  This limit is
27300 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a   not currently.*
27310 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75  * enforced, thou
27320 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  gh that might be
27330 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66   added in some f
27340 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
27350 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  .** SQLite.</dd>
27360 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
27370 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
27380 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  _ARG]] ^(<dt>SQL
27390 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
273a0 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c  ON_ARG</dt>.** <
273b0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
273c0 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e  umber of argumen
273d0 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e  ts on a function
273e0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
273f0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54  [SQLITE_LIMIT_AT
27400 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53  TACHED]] ^(<dt>S
27410 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
27420 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  CHED</dt>.** <dd
27430 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
27440 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c  ber of [ATTACH |
27450 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
27460 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a  ses].)^</dd>.**.
27470 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
27480 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
27490 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74  ENGTH]].** ^(<dt
274a0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
274b0 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
274c0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
274d0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
274e0 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
274f0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
27500 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
27510 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
27520 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
27530 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
27540 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20  BLE_NUMBER]].** 
27550 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
27560 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
27570 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ER</dt>.** <dd>T
27580 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78  he maximum index
27590 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b   number of any [
275a0 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e  parameter] in an
275b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29   SQL statement.)
275c0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
275d0 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
275e0 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  EPTH]] ^(<dt>SQL
275f0 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45  ITE_LIMIT_TRIGGE
27600 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
27610 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
27620 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73 69  depth of recursi
27630 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e  on for triggers.
27640 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e  </dd>)^.** </dl>
27650 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
27660 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20  TE_LIMIT_LENGTH 
27670 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27680 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
27690 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45  ITE_LIMIT_SQL_LE
276a0 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20  NGTH            
276b0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
276c0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d  LITE_LIMIT_COLUM
276d0 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  N               
276e0 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
276f0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52  QLITE_LIMIT_EXPR
27700 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
27710 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
27720 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d  SQLITE_LIMIT_COM
27730 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20  POUND_SELECT    
27740 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65         4.#define
27750 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44   SQLITE_LIMIT_VD
27760 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20  BE_OP           
27770 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e          5.#defin
27780 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  e SQLITE_LIMIT_F
27790 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20  UNCTION_ARG     
277a0 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69           6.#defi
277b0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
277c0 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20 20  ATTACHED        
277d0 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
277e0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
277f0 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45  _LIKE_PATTERN_LE
27800 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64 65  NGTH       8.#de
27810 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
27820 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45  T_VARIABLE_NUMBE
27830 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23 64  R           9.#d
27840 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
27850 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48  IT_TRIGGER_DEPTH
27860 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a              10..
27870 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27880 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c  Compiling An SQL
27890 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45   Statement.** KE
278a0 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61  YWORDS: {SQL sta
278b0 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d  tement compiler}
278c0 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74  .**.** To execut
278d0 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20  e an SQL query, 
278e0 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62 65  it must first be
278f0 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61   compiled into a
27900 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72   byte-code.** pr
27910 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20  ogram using one 
27920 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
27930 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  s..**.** The fir
27940 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62  st argument, "db
27950 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61 73  ", is a [databas
27960 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62  e connection] ob
27970 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a  tained from a.**
27980 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66 75   prior successfu
27990 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  l call to [sqlit
279a0 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
279b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20  ite3_open_v2()] 
279c0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
279d0 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64  pen16()].  The d
279e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
279f0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65  on must not have
27a00 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a   been closed..**
27a10 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
27a20 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c  rgument, "zSql",
27a30 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   is the statemen
27a40 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
27a50 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20  , encoded.** as 
27a60 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20  either UTF-8 or 
27a70 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c  UTF-16.  The sql
27a80 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 61  ite3_prepare() a
27a90 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
27aa0 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72  re_v2().** inter
27ab0 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c  faces use UTF-8,
27ac0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
27ad0 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c  pare16() and sql
27ae0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
27af0 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31  2().** use UTF-1
27b00 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  6..**.** ^If the
27b10 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20   nByte argument 
27b20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72  is less than zer
27b30 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20  o, then zSql is 
27b40 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a  read up to the.*
27b50 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72  * first zero ter
27b60 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79  minator. ^If nBy
27b70 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  te is non-negati
27b80 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74  ve, then it is t
27b90 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75  he maximum.** nu
27ba0 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20 72  mber of  bytes r
27bb0 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20  ead from zSql.  
27bc0 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e  ^When nByte is n
27bd0 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65  on-negative, the
27be0 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20  .** zSql string 
27bf0 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20 74  ends at either t
27c00 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27 20  he first '\000' 
27c10 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61 72  or '\u0000' char
27c20 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20  acter or.** the 
27c30 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77  nByte-th byte, w
27c40 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66  hichever comes f
27c50 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c  irst. If the cal
27c60 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61  ler knows.** tha
27c70 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20 73  t the supplied s
27c80 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72  tring is nul-ter
27c90 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68  minated, then th
27ca0 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a  ere is a small.*
27cb0 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64  * performance ad
27cc0 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61  vantage to be ga
27cd0 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67 20  ined by passing 
27ce0 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74  an nByte paramet
27cf0 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71  er that.** is eq
27d00 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65  ual to the numbe
27d10 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
27d20 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c  e input string <
27d30 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a  i>including</i>.
27d40 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69  ** the nul-termi
27d50 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20 74  nator bytes as t
27d60 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74 65  his saves SQLite
27d70 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a   from having to.
27d80 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f  ** make a copy o
27d90 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  f the input stri
27da0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a  ng..**.** ^If pz
27db0 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  Tail is not NULL
27dc0 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73   then *pzTail is
27dd0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
27de0 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65  o the first byte
27df0 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64  .** past the end
27e00 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51   of the first SQ
27e10 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a  L statement in z
27e20 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74  Sql.  These rout
27e30 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d  ines only.** com
27e40 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73  pile the first s
27e50 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
27e60 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20  , so *pzTail is 
27e70 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
27e80 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73  .** what remains
27e90 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a   uncompiled..**.
27ea0 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c  ** ^*ppStmt is l
27eb0 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20  eft pointing to 
27ec0 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70  a compiled [prep
27ed0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
27ee0 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65  that can be.** e
27ef0 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73  xecuted using [s
27f00 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20  qlite3_step()]. 
27f10 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e   ^If there is an
27f20 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20   error, *ppStmt 
27f30 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c  is set.** to NUL
27f40 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75  L.  ^If the inpu
27f50 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20  t text contains 
27f60 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69  no SQL (if the i
27f70 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79  nput is an empty
27f80 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20  .** string or a 
27f90 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70  comment) then *p
27fa0 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20  pStmt is set to 
27fb0 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  NULL..** The cal
27fc0 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69  ling procedure i
27fd0 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
27fe0 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63  r deleting the c
27ff0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73  ompiled.** SQL s
28000 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b  tatement using [
28010 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
28020 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73  ()] after it has
28030 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
28040 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79  t..** ppStmt may
28050 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a   not be NULL..**
28060 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c  .** ^On success,
28070 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   the sqlite3_pre
28080 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66  pare() family of
28090 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
280a0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a   [SQLITE_OK];.**
280b0 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   otherwise an [e
280c0 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
280d0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  turned..**.** Th
280e0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
280f0 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74  e_v2() and sqlit
28100 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
28110 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  ) interfaces are
28120 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  .** recommended 
28130 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67  for all new prog
28140 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c  rams. The two ol
28150 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61  der interfaces a
28160 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66  re retained.** f
28170 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
28180 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20  patibility, but 
28190 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73  their use is dis
281a0 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e  couraged..** ^In
281b0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
281c0 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72  aces, the prepar
281d0 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
281e0 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64  that is returned
281f0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
28200 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e  tmt] object) con
28210 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20  tains a copy of 
28220 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20  the.** original 
28230 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63  SQL text. This c
28240 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74  auses the [sqlit
28250 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72  e3_step()] inter
28260 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76  face to.** behav
28270 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e  e differently in
28280 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a   three ways:.**.
28290 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a  ** <ol>.** <li>.
282a0 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62  ** ^If the datab
282b0 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
282c0 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72  es, instead of r
282d0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
282e0 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a  _SCHEMA] as it.*
282f0 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f  * always used to
28300 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74   do, [sqlite3_st
28310 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d  ep()] will autom
28320 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69  atically recompi
28330 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74  le the SQL.** st
28340 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20  atement and try 
28350 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e  to run it again.
28360 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20  .** </li>.**.** 
28370 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e  <li>.** ^When an
28380 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b   error occurs, [
28390 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
283a0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20  will return one 
283b0 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a  of the detailed.
283c0 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d  ** [error codes]
283d0 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72   or [extended er
283e0 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68  ror codes].  ^Th
283f0 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f  e legacy behavio
28400 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73  r was that.** [s
28410 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
28420 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e  ould only return
28430 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49   a generic [SQLI
28440 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74  TE_ERROR] result
28450 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65   code.** and the
28460 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75   application wou
28470 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20  ld have to make 
28480 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f  a second call to
28490 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
284a0 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74  )].** in order t
284b0 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72  o find the under
284c0 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74  lying cause of t
284d0 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68  he problem. With
284e0 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72   the "v2" prepar
284f0 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c  e.** interfaces,
28500 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
28510 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65  reason for the e
28520 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
28530 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
28540 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
28550 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65  >.** ^If the spe
28560 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e  cific value boun
28570 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20  d to [parameter 
28580 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72  | host parameter
28590 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45  ] in the .** WHE
285a0 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20  RE clause might 
285b0 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68  influence the ch
285c0 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c  oice of query pl
285d0 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65  an for a stateme
285e0 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  nt,.** then the 
285f0 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62  statement will b
28600 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
28610 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69  recompiled, as i
28620 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e  f there had been
28630 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68   .** a schema ch
28640 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72  ange, on the fir
28650 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  st  [sqlite3_ste
28660 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77  p()] call follow
28670 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a  ing any change.*
28680 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  * to the [sqlite
28690 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69  3_bind_text | bi
286a0 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20  ndings] of that 
286b0 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a  [parameter]. .**
286c0 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76   ^The specific v
286d0 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c  alue of WHERE-cl
286e0 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d  ause [parameter]
286f0 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65   might influence
28700 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20   the .** choice 
28710 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66  of query plan if
28720 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
28730 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20  s the left-hand 
28740 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d  side of a [LIKE]
28750 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70  .** or [GLOB] op
28760 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65  erator or if the
28770 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f   parameter is co
28780 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64  mpared to an ind
28790 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  exed column.** a
287a0 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45  nd the [SQLITE_E
287b0 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d  NABLE_STAT3] com
287c0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
287d0 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20   is enabled..** 
287e0 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  the .** </li>.**
287f0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45   </ol>.*/.SQLITE
28800 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
28810 5f 70 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69  _prepare(.  sqli
28820 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
28830 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
28840 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
28850 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
28860 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
28870 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
28880 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
28890 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
288a0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
288b0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
288c0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
288d0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
288e0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
288f0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
28900 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
28910 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
28920 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
28930 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
28940 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
28950 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
28960 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
28970 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
28980 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
28990 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
289a0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
289b0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
289c0 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
289d0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
289e0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
289f0 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
28a00 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
28a10 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
28a20 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
28a30 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
28a40 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
28a50 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
28a60 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
28a70 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
28a80 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
28a90 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  ql */.);.SQLITE_
28aa0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
28ab0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
28ac0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
28ad0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
28ae0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
28af0 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
28b00 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
28b10 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
28b20 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
28b30 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
28b40 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
28b50 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
28b60 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
28b70 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
28b80 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
28b90 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
28ba0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
28bb0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
28bc0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
28bd0 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
28be0 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45  Sql */.);.SQLITE
28bf0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
28c00 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20  _prepare16_v2(. 
28c10 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
28c20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
28c30 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
28c40 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
28c50 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
28c60 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
28c70 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
28c80 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
28c90 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
28ca0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
28cb0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
28cc0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
28cd0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
28ce0 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
28cf0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
28d00 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
28d10 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
28d20 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
28d30 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f  of zSql */.);../
28d40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
28d50 65 74 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d  etrieving Statem
28d60 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54  ent SQL.**.** ^T
28d70 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 63 61  his interface ca
28d80 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 74  n be used to ret
28d90 72 69 65 76 65 20 61 20 73 61 76 65 64 20 63 6f  rieve a saved co
28da0 70 79 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e  py of the origin
28db0 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75  al.** SQL text u
28dc0 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
28dd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
28de0 65 6e 74 5d 20 69 66 20 74 68 61 74 20 73 74 61  ent] if that sta
28df0 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f  tement was.** co
28e00 6d 70 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74  mpiled using eit
28e10 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  her [sqlite3_pre
28e20 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
28e30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
28e40 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  _v2()]..*/.SQLIT
28e50 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
28e60 20 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71   *sqlite3_sql(sq
28e70 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
28e80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
28e90 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
28ea0 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
28eb0 6e 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61  nt Writes The Da
28ec0 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68  tabase.**.** ^Th
28ed0 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  e sqlite3_stmt_r
28ee0 65 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72  eadonly(X) inter
28ef0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75  face returns tru
28f00 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a  e (non-zero) if.
28f10 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74  ** and only if t
28f20 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
28f30 74 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20  tement] X makes 
28f40 6e 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65  no direct change
28f50 73 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  s to.** the cont
28f60 65 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  ent of the datab
28f70 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20  ase file..**.** 
28f80 4e 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69  Note that [appli
28f90 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53  cation-defined S
28fa0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72  QL functions] or
28fb0 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62  .** [virtual tab
28fc0 6c 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67  les] might chang
28fd0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  e the database i
28fe0 6e 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73  ndirectly as a s
28ff0 69 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a  ide effect.  .**
29000 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
29010 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  if an applicatio
29020 6e 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63  n defines a func
29030 74 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68  tion "eval()" th
29040 61 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71  at .** calls [sq
29050 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74  lite3_exec()], t
29060 68 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  hen the followin
29070 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  g SQL statement 
29080 77 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20  would.** change 
29090 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
290a0 65 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65  e through side-e
290b0 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ffects:.**.** <b
290c0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
290d0 2a 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61  **    SELECT eva
290e0 6c 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74  l('DELETE FROM t
290f0 31 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20  1') FROM t2;.** 
29100 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
29110 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65  te>.**.** But be
29120 63 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43  cause the [SELEC
29130 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65  T] statement doe
29140 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65  s not change the
29150 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a   database file.*
29160 2a 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69  * directly, sqli
29170 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
29180 79 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20  y() would still 
29190 72 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a  return true.)^.*
291a0 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f  *.** ^Transactio
291b0 6e 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d  n control statem
291c0 65 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45  ents such as [BE
291d0 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20  GIN], [COMMIT], 
291e0 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b  [ROLLBACK],.** [
291f0 53 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20  SAVEPOINT], and 
29200 5b 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20  [RELEASE] cause 
29210 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
29220 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
29230 6e 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65  n true,.** since
29240 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20   the statements 
29250 74 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f  themselves do no
29260 74 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66  t actually modif
29270 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62  y the database b
29280 75 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65  ut.** rather the
29290 79 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69  y control the ti
292a0 6d 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68  ming of when oth
292b0 65 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f  er statements mo
292c0 64 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74  dify the .** dat
292d0 61 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54  abase.  ^The [AT
292e0 54 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43  TACH] and [DETAC
292f0 48 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c  H] statements al
29300 73 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69  so cause.** sqli
29310 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
29320 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72  y() to return tr
29330 75 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20  ue since, while 
29340 74 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73  those statements
29350 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63  .** change the c
29360 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20  onfiguration of 
29370 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
29380 63 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e  ction, they do n
29390 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e  ot make .** chan
293a0 67 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65  ges to the conte
293b0 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
293c0 73 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b  se files on disk
293d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
293e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
293f0 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
29400 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
29410 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29420 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
29430 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
29440 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
29450 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
29460 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
29470 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
29480 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
29490 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
294a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
294b0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
294c0 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
294d0 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
294e0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
294f0 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
29500 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
29510 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
29520 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
29530 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
29540 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
29550 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
29560 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
29570 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
29580 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
29590 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
295a0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
295b0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
295c0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
295d0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
295e0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
295f0 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
29600 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
29610 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
29620 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
29630 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
29640 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
29650 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
29660 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
29670 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
29680 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
29690 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
296a0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
296b0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
296c0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
296d0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
296e0 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
296f0 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
29700 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
29710 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
29720 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
29730 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
29740 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
29750 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
29760 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  n open..*/.SQLIT
29770 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
29780 33 5f 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69  3_stmt_busy(sqli
29790 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
297a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e  ** CAPI3REF: Dyn
297b0 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56  amically Typed V
297c0 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b  alue Object.** K
297d0 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63  EYWORDS: {protec
297e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
297f0 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20  e} {unprotected 
29800 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a  sqlite3_value}.*
29810 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
29820 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c   the sqlite3_val
29830 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70  ue object to rep
29840 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65  resent all value
29850 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
29860 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74   stored in a dat
29870 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c  abase table. SQL
29880 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
29890 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74   typing.** for t
298a0 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f  he values it sto
298b0 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74  res.  ^Values st
298c0 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f  ored in sqlite3_
298d0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a  value objects.**
298e0 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73   can be integers
298f0 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  , floating point
29900 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73   values, strings
29910 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c  , BLOBs, or NULL
29920 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74  ..**.** An sqlit
29930 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
29940 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22 70  may be either "p
29950 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e  rotected" or "un
29960 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53  protected"..** S
29970 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20 72  ome interfaces r
29980 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63 74  equire a protect
29990 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
299a0 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61  .  Other interfa
299b0 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65  ces.** will acce
299c0 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f 74  pt either a prot
299d0 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72  ected or an unpr
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 2e 0a 2a 2a 20 45 76 65 72 79 20  value..** Every 
29a00 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
29a10 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76  ccepts sqlite3_v
29a20 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73  alue arguments s
29a30 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74  pecifies.** whet
29a40 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65  her or not it re
29a50 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63 74  quires a protect
29a60 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29a70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d  ..**.** The term
29a80 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e  s "protected" an
29a90 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20  d "unprotected" 
29aa0 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65 72  refer to whether
29ab0 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74   or not.** a mut
29ac0 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20  ex is held.  An 
29ad0 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69  internal mutex i
29ae0 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f  s held for a pro
29af0 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
29b00 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62  3_value object b
29b10 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68  ut no mutex is h
29b20 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f  eld for an unpro
29b30 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65  tected.** sqlite
29b40 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20  3_value object. 
29b50 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   If SQLite is co
29b60 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e  mpiled to be sin
29b70 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20  gle-threaded.** 
29b80 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48  (with [SQLITE_TH
29b90 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20  READSAFE=0] and 
29ba0 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68  with [sqlite3_th
29bb0 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74 75  readsafe()] retu
29bc0 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69  rning 0).** or i
29bd0 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20  f SQLite is run 
29be0 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65  in one of reduce
29bf0 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a  d mutex modes .*
29c00 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
29c10 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f  _SINGLETHREAD] o
29c20 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  r [SQLITE_CONFIG
29c30 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a  _MULTITHREAD].**
29c40 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e   then there is n
29c50 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  o distinction be
29c60 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
29c70 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
29c80 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
29c90 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65   objects and the
29ca0 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  y can be used in
29cb0 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20  terchangeably.  
29cc0 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20  However,.** for 
29cd0 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72  maximum code por
29ce0 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20 72  tability it is r
29cf0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
29d00 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
29d10 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64  still make the d
29d20 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65  istinction betwe
29d30 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64  en protected and
29d40 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20   unprotected.** 
29d50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
29d60 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20  jects even when 
29d70 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65 71  not strictly req
29d80 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  uired..**.** ^Th
29d90 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
29da0 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72 65  objects that are
29db0 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61 6d   passed as param
29dc0 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a  eters into the.*
29dd0 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
29de0 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e   of [application
29df0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
29e00 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74  ctions] are prot
29e10 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73  ected..** ^The s
29e20 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
29e30 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ect returned by.
29e40 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
29e50 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75  mn_value()] is u
29e60 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55  nprotected..** U
29e70 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
29e80 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
29e90 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
29ea0 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74  d with.** [sqlit
29eb0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
29ec0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
29ed0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a  bind_value()]..*
29ee0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  * The [sqlite3_v
29ef0 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69  alue_blob | sqli
29f00 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29  te3_value_type()
29f10 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69  ] family of.** i
29f20 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69 72  nterfaces requir
29f30 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  e protected sqli
29f40 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
29f50 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  s..*/.typedef st
29f60 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33  ruct Mem sqlite3
29f70 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _value;../*.** C
29f80 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e  API3REF: SQL Fun
29f90 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62  ction Context Ob
29fa0 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ject.**.** The c
29fb0 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68 20  ontext in which 
29fc0 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  an SQL function 
29fd0 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f 72  executes is stor
29fe0 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69  ed in an.** sqli
29ff0 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65  te3_context obje
2a000 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20  ct.  ^A pointer 
2a010 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f  to an sqlite3_co
2a020 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20  ntext object.** 
2a030 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74 20  is always first 
2a040 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70  parameter to [ap
2a050 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
2a060 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d  d SQL functions]
2a070 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
2a080 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2a090 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
2a0a0 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61  entation will pa
2a0b0 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74  ss this.** point
2a0c0 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20  er through into 
2a0d0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2a0e0 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73  3_result_int | s
2a0f0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d  qlite3_result()]
2a100 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67  ,.** [sqlite3_ag
2a110 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2a120 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  )], [sqlite3_use
2a130 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73  r_data()],.** [s
2a140 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
2a150 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71  b_handle()], [sq
2a160 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2a170 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20  a()],.** and/or 
2a180 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78  [sqlite3_set_aux
2a190 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65  data()]..*/.type
2a1a0 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
2a1b0 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74  e3_context sqlit
2a1c0 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a  e3_context;../*.
2a1d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e  ** CAPI3REF: Bin
2a1e0 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50  ding Values To P
2a1f0 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
2a200 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ts.** KEYWORDS: 
2a210 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d  {host parameter}
2a220 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2a230 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  s} {host paramet
2a240 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57  er name}.** KEYW
2a250 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d  ORDS: {SQL param
2a260 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d  eter} {SQL param
2a270 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65  eters} {paramete
2a280 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a  r binding}.**.**
2a290 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74   ^(In the SQL st
2a2a0 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70  atement text inp
2a2b0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70  ut to [sqlite3_p
2a2c0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2a2d0 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a   its variants,.*
2a2e0 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62  * literals may b
2a2f0 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20  e replaced by a 
2a300 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74  [parameter] that
2a310 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20   matches one of 
2a320 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d  following.** tem
2a330 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  plates:.**.** <u
2a340 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a  l>.** <li>  ?.**
2a350 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c   <li>  ?NNN.** <
2a360 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69  li>  :VVV.** <li
2a370 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  @VVV.** <li> 
2a380 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a   $VVV.** </ul>.*
2a390 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70  *.** In the temp
2a3a0 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e  lates above, NNN
2a3b0 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69   represents an i
2a3c0 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a  nteger literal,.
2a3d0 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72 65  ** and VVV repre
2a3e0 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75  sents an alphanu
2a3f0 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65 72  meric identifier
2a400 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73  .)^  ^The values
2a410 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72   of these.** par
2a420 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61  ameters (also ca
2a430 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d  lled "host param
2a440 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22  eter names" or "
2a450 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29  SQL parameters")
2a460 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75  .** can be set u
2a470 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
2a480 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2a490 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  es defined here.
2a4a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2a4b0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2a4c0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
2a4d0 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61  () routines is a
2a4e0 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  lways.** a point
2a4f0 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
2a500 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20  e3_stmt] object 
2a510 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a  returned from.**
2a520 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a530 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76  e_v2()] or its v
2a540 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e  ariants..**.** ^
2a550 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
2a560 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2a570 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72 61   of the SQL para
2a580 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e  meter to be set.
2a590 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  .** ^The leftmos
2a5a0 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  t SQL parameter 
2a5b0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
2a5c0 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61  1.  ^When the sa
2a5d0 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20  me named.** SQL 
2a5e0 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73 65  parameter is use
2a5f0 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65  d more than once
2a600 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62  , second and sub
2a610 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72  sequent.** occur
2a620 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65 20  rences have the 
2a630 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68  same index as th
2a640 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e  e first occurren
2a650 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65  ce..** ^The inde
2a660 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61  x for named para
2a670 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f  meters can be lo
2a680 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74 68  oked up using th
2a690 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  e.** [sqlite3_bi
2a6a0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2a6b0 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65 73  ex()] API if des
2a6c0 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65  ired.  ^The inde
2a6d0 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20  x.** for "?NNN" 
2a6e0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74 68  parameters is th
2a6f0 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a  e value of NNN..
2a700 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75  ** ^The NNN valu
2a710 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65  e must be betwee
2a720 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c  n 1 and the [sql
2a730 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
2a740 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49   parameter [SQLI
2a750 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
2a760 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75  E_NUMBER] (defau
2a770 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a  lt value: 999)..
2a780 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64  **.** ^The third
2a790 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2a7a0 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74   value to bind t
2a7b0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e  o the parameter.
2a7c0 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73  .**.** ^(In thos
2a7d0 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  e routines that 
2a7e0 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61 72  have a fourth ar
2a7f0 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75  gument, its valu
2a800 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  e is the.** numb
2a810 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2a820 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54  he parameter.  T
2a830 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20  o be clear: the 
2a840 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2a850 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74  number of <u>byt
2a860 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61  es</u> in the va
2a870 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  lue, not the num
2a880 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
2a890 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.)^.** ^If the 
2a8a0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
2a8b0 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2a8c0 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
2a8d0 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68 65  string is.** the
2a8e0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2a8f0 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73 74   up to the first
2a900 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
2a910 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65  ..** If a non-ne
2a920 67 61 74 69 76 65 20 66 6f 75 72 74 68 20 70 61  gative fourth pa
2a930 72 61 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69  rameter is provi
2a940 64 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ded to sqlite3_b
2a950 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72  ind_text().** or
2a960 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
2a970 78 74 31 36 28 29 20 74 68 65 6e 20 74 68 61 74  xt16() then that
2a980 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
2a990 62 65 20 74 68 65 20 62 79 74 65 20 6f 66 66 73  be the byte offs
2a9a0 65 74 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20  et.** where the 
2a9b0 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77  NUL terminator w
2a9c0 6f 75 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d  ould occur assum
2a9d0 69 6e 67 20 74 68 65 20 73 74 72 69 6e 67 20 77  ing the string w
2a9e0 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69  ere NUL.** termi
2a9f0 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
2aa00 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
2aa10 63 75 72 20 61 74 20 62 79 74 65 20 6f 66 66 73  cur at byte offs
2aa20 65 74 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a  ets less than .*
2aa30 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  * the value of t
2aa40 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2aa50 74 65 72 20 74 68 65 6e 20 74 68 65 20 72 65 73  ter then the res
2aa60 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61  ulting string va
2aa70 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74  lue will.** cont
2aa80 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
2aa90 73 2e 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f  s.  The result o
2aaa0 66 20 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e  f expressions in
2aab0 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a  volving strings.
2aac0 2a 2a 20 77 69 74 68 20 65 6d 62 65 64 64 65 64  ** with embedded
2aad0 20 4e 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e   NULs is undefin
2aae0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
2aaf0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  ifth argument to
2ab00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
2ab10 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69  ob(), sqlite3_bi
2ab20 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a  nd_text(), and.*
2ab30 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
2ab40 65 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73  ext16() is a des
2ab50 74 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20  tructor used to 
2ab60 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42  dispose of the B
2ab70 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67  LOB or.** string
2ab80 20 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61   after SQLite ha
2ab90 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
2aba0 69 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75  it.  ^The destru
2abb0 63 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a  ctor is called.*
2abc0 2a 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  * to dispose of 
2abd0 74 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  the BLOB or stri
2abe0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63  ng even if the c
2abf0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  all to sqlite3_b
2ac00 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73  ind_blob(),.** s
2ac10 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2ac20 28 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  (), or sqlite3_b
2ac30 69 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69  ind_text16() fai
2ac40 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65  ls.  .** ^If the
2ac50 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
2ac60 69 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61  is.** the specia
2ac70 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  l value [SQLITE_
2ac80 53 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51  STATIC], then SQ
2ac90 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61  Lite assumes tha
2aca0 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  t the.** informa
2acb0 74 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69  tion is in stati
2acc0 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61  c, unmanaged spa
2acd0 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20  ce and does not 
2ace0 6e 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64  need to be freed
2acf0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66  ..** ^If the fif
2ad00 74 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20  th argument has 
2ad10 74 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54  the value [SQLIT
2ad20 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68  E_TRANSIENT], th
2ad30 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b  en.** SQLite mak
2ad40 65 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61  es its own priva
2ad50 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64  te copy of the d
2ad60 61 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c  ata immediately,
2ad70 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73   before.** the s
2ad80 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
2ad90 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e  routine returns.
2ada0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2adb0 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
2adc0 62 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64  b() routine bind
2add0 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67  s a BLOB of leng
2ade0 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20  th N that.** is 
2adf0 66 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f  filled with zero
2ae00 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62  es.  ^A zeroblob
2ae10 20 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d   uses a fixed am
2ae20 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a  ount of memory.*
2ae30 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67  * (just an integ
2ae40 65 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73  er to hold its s
2ae50 69 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73  ize) while it is
2ae60 20 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64   being processed
2ae70 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61  ..** Zeroblobs a
2ae80 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73  re intended to s
2ae90 65 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c  erve as placehol
2aea0 64 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77  ders for BLOBs w
2aeb0 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20  hose.** content 
2aec0 69 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e  is later written
2aed0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
2aee0 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69  e3_blob_open | i
2aef0 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
2af00 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  I/O] routines..*
2af10 2a 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61  * ^A negative va
2af20 6c 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f  lue for the zero
2af30 62 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20  blob results in 
2af40 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
2af50 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  OB..**.** ^If an
2af60 79 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  y of the sqlite3
2af70 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e  _bind_*() routin
2af80 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69  es are called wi
2af90 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
2afa0 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72  r.** for the [pr
2afb0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2afc0 5d 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70  ] or with a prep
2afd0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66  ared statement f
2afe0 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c  or which.** [sql
2aff0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2b000 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72   been called mor
2b010 65 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20  e recently than 
2b020 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2b030 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63  ],.** then the c
2b040 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  all will return 
2b050 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e  [SQLITE_MISUSE].
2b060 20 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33    If any sqlite3
2b070 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74  _bind_().** rout
2b080 69 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20  ine is passed a 
2b090 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b0a0 65 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65  ent] that has be
2b0b0 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68  en finalized, th
2b0c0 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75  e.** result is u
2b0d0 6e 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f  ndefined and pro
2b0e0 62 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a  bably harmful..*
2b0f0 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61  *.** ^Bindings a
2b100 72 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62  re not cleared b
2b110 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72  y the [sqlite3_r
2b120 65 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e  eset()] routine.
2b130 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72  .** ^Unbound par
2b140 61 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65  ameters are inte
2b150 72 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e  rpreted as NULL.
2b160 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2b170 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69  te3_bind_* routi
2b180 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
2b190 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
2b1a0 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f  s or an.** [erro
2b1b0 72 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68  r code] if anyth
2b1c0 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a  ing goes wrong..
2b1d0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47  ** ^[SQLITE_RANG
2b1e0 45 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  E] is returned i
2b1f0 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a  f the parameter.
2b200 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20  ** index is out 
2b210 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c  of range.  ^[SQL
2b220 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65  ITE_NOMEM] is re
2b230 74 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63  turned if malloc
2b240 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20  () fails..**.** 
2b250 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2b260 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2b270 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b  r_count()],.** [
2b280 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b290 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20  ameter_name()], 
2b2a0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  and [sqlite3_bin
2b2b0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2b2c0 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
2b2d0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2b2e0 62 69 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65  bind_blob(sqlite
2b2f0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b300 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e  nst void*, int n
2b310 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2b320 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2b330 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
2b340 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
2b350 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
2b360 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2b370 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69  t sqlite3_bind_i
2b380 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
2b390 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c  , int, int);.SQL
2b3a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2b3b0 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73  te3_bind_int64(s
2b3c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b3d0 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
2b3e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2b3f0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e  t sqlite3_bind_n
2b400 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ull(sqlite3_stmt
2b410 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  *, int);.SQLITE_
2b420 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2b430 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65  bind_text(sqlite
2b440 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
2b450 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e  nst char*, int n
2b460 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
2b470 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
2b480 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  t sqlite3_bind_t
2b490 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
2b4a0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
2b4b0 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64  void*, int, void
2b4c0 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c  (*)(void*));.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 76 61 6c 75 65 28 73  te3_bind_value(s
2b4f0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b500 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
2b510 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
2b520 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
2b530 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
2b540 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2b550 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
2b560 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
2b570 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
2b580 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
2b590 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2b5a0 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
2b5b0 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
2b5c0 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
2b5d0 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2b5e0 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
2b5f0 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
2b600 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
2b610 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
2b620 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
2b630 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
2b640 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
2b650 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
2b660 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
2b670 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2b680 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
2b690 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
2b6a0 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
2b6b0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
2b6c0 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
2b6d0 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
2b6e0 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
2b6f0 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
2b700 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
2b710 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
2b720 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
2b730 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
2b740 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
2b750 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
2b760 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
2b770 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
2b780 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
2b790 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
2b7a0 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
2b7b0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2b7c0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2b7d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2b7e0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2b7f0 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
2b800 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
2b810 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2b820 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2b830 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2b840 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2b850 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c  ameter_count(sql
2b860 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2b870 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
2b880 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72  me Of A Host Par
2b890 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68  ameter.**.** ^Th
2b8a0 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  e sqlite3_bind_p
2b8b0 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c  arameter_name(P,
2b8c0 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  N) interface ret
2b8d0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  urns.** the name
2b8e0 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51   of the N-th [SQ
2b8f0 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20  L parameter] in 
2b900 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2b910 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2b920 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20  (SQL parameters 
2b930 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e  of the form "?NN
2b940 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
2b950 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
2b960 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20  .** have a name 
2b970 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74 72  which is the str
2b980 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  ing "?NNN" or ":
2b990 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
2b9a0 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70  r "$AAA".** resp
2b9b0 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20  ectively..** In 
2b9c0 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
2b9d0 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20   initial ":" or 
2b9e0 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f  "$" or "@" or "?
2b9f0 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64  ".** is included
2ba00 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65 20   as part of the 
2ba10 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61  name.)^.** ^Para
2ba20 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2ba30 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61  rm "?" without a
2ba40 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67   following integ
2ba50 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a  er have no name.
2ba60 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65 72  ** and are refer
2ba70 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c  red to as "namel
2ba80 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f  ess" or "anonymo
2ba90 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a  us parameters"..
2baa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
2bab0 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20   host parameter 
2bac0 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20  has an index of 
2bad0 31 2c 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20  1, not 0..**.** 
2bae0 5e 49 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20  ^If the value N 
2baf0 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  is out of range 
2bb00 6f 72 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70  or if the N-th p
2bb10 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e  arameter is.** n
2bb20 61 6d 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55  ameless, then NU
2bb30 4c 4c 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  LL is returned. 
2bb40 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2bb50 74 72 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61  tring is.** alwa
2bb60 79 73 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f  ys in UTF-8 enco
2bb70 64 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65  ding even if the
2bb80 20 6e 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72   named parameter
2bb90 20 77 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   was.** original
2bba0 6c 79 20 73 70 65 63 69 66 69 65 64 20 61 73 20  ly specified as 
2bbb0 55 54 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74  UTF-16 in [sqlit
2bbc0 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20  e3_prepare16()] 
2bbd0 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  or.** [sqlite3_p
2bbe0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a  repare16_v2()]..
2bbf0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
2bc00 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2bc10 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2bc20 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2bc30 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2bc40 6f 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  ount()], and.** 
2bc50 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2bc60 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d  rameter_index()]
2bc70 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2bc80 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2bc90 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2bca0 65 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  er_name(sqlite3_
2bcb0 73 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a  stmt*, int);../*
2bcc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
2bcd0 64 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74  dex Of A Paramet
2bce0 65 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20  er With A Given 
2bcf0 4e 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75  Name.**.** ^Retu
2bd00 72 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  rn the index of 
2bd10 61 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  an SQL parameter
2bd20 20 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e   given its name.
2bd30 20 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20    ^The.** index 
2bd40 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69  value returned i
2bd50 73 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75  s suitable for u
2bd60 73 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  se as the second
2bd70 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f  .** parameter to
2bd80 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2bd90 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64  lob|sqlite3_bind
2bda0 28 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a  ()].  ^A zero.**
2bdb0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2bdc0 6e 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61  no matching para
2bdd0 6d 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20  meter is found. 
2bde0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a   ^The parameter.
2bdf0 2a 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20  ** name must be 
2be00 67 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65  given in UTF-8 e
2be10 76 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69  ven if the origi
2be20 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  nal statement.**
2be30 20 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72   was prepared fr
2be40 6f 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75  om UTF-16 text u
2be50 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
2be60 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a  epare16_v2()]..*
2be70 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
2be80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2be90 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2bea0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
2beb0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
2bec0 75 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  unt()], and.** [
2bed0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2bee0 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
2bef0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
2bf00 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
2bf10 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2bf20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
2bf30 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
2bf40 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2bf50 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
2bf60 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
2bf70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
2bf80 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
2bf90 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
2bfa0 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
2bfb0 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
2bfc0 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
2bfd0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2bfe0 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
2bff0 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2c000 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
2c010 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
2c020 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
2c030 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
2c040 4e 55 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  NULL..*/.SQLITE_
2c050 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2c060 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73  clear_bindings(s
2c070 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
2c080 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2c090 4e 75 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e  Number Of Column
2c0a0 73 20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65  s In A Result Se
2c0b0 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  t.**.** ^Return 
2c0c0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2c0d0 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
2c0e0 75 6c 74 20 73 65 74 20 72 65 74 75 72 6e 65 64  ult set returned
2c0f0 20 62 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70   by the.** [prep
2c100 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
2c110 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
2c120 65 74 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d  eturns 0 if pStm
2c130 74 20 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73  t is an SQL.** s
2c140 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f  tatement that do
2c150 65 73 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61  es not return da
2c160 74 61 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  ta (for example 
2c170 61 6e 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a  an [UPDATE])..**
2c180 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2c190 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e  qlite3_data_coun
2c1a0 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  t()].*/.SQLITE_A
2c1b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
2c1c0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69  olumn_count(sqli
2c1d0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
2c1e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2c1f0 46 3a 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20  F: Column Names 
2c200 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2c210 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2c220 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65  tines return the
2c230 20 6e 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74   name assigned t
2c240 6f 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 63  o a particular c
2c250 6f 6c 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  olumn.** in the 
2c260 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
2c270 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2c280 6e 74 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  nt.  ^The sqlite
2c290 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a  3_column_name().
2c2a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
2c2b0 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74  urns a pointer t
2c2c0 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  o a zero-termina
2c2d0 74 65 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67  ted UTF-8 string
2c2e0 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
2c2f0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
2c300 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2c310 72 20 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d  r to a zero-term
2c320 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36  inated.** UTF-16
2c330 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66   string.  ^The f
2c340 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2c350 73 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20  s the [prepared 
2c360 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68  statement].** th
2c370 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
2c380 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
2c390 6d 65 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e  ment. ^The secon
2c3a0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
2c3b0 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d  he.** column num
2c3c0 62 65 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d  ber.  ^The leftm
2c3d0 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75  ost column is nu
2c3e0 6d 62 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mber 0..**.** ^T
2c3f0 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69  he returned stri
2c400 6e 67 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61  ng pointer is va
2c410 6c 69 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72  lid until either
2c420 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2c430 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20  tatement].** is 
2c440 64 65 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71  destroyed by [sq
2c450 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c460 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2c470 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2c480 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2c490 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2c4a0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2c4b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2c4c0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2c4d0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2c4e0 68 65 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a  he next call to.
2c4f0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2c500 6e 5f 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69  n_name() or sqli
2c510 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2c520 36 28 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  6() on the same 
2c530 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  column..**.** ^I
2c540 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  f sqlite3_malloc
2c550 28 29 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20  () fails during 
2c560 74 68 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f  the processing o
2c570 66 20 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65  f either routine
2c580 0a 2a 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65  .** (for example
2c590 20 64 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72   during a conver
2c5a0 73 69 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20  sion from UTF-8 
2c5b0 74 6f 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20  to UTF-16) then 
2c5c0 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  a.** NULL pointe
2c5d0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  r is returned..*
2c5e0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
2c5f0 66 20 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  f a result colum
2c600 6e 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f  n is the value o
2c610 66 20 74 68 65 20 22 41 53 22 20 63 6c 61 75 73  f the "AS" claus
2c620 65 20 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f  e for.** that co
2c630 6c 75 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69  lumn, if there i
2c640 73 20 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20  s an AS clause. 
2c650 20 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20   If there is no 
2c660 41 53 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65  AS clause.** the
2c670 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2c680 65 20 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70  e column is unsp
2c690 65 63 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20  ecified and may 
2c6a0 63 68 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f  change from.** o
2c6b0 6e 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ne release of SQ
2c6c0 4c 69 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74  Lite to the next
2c6d0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2c6e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2c6f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2c700 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c710 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50  nt N);.SQLITE_AP
2c720 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2c730 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2c740 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  e16(sqlite3_stmt
2c750 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a  *, int N);../*.*
2c760 2a 20 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72  * CAPI3REF: Sour
2c770 63 65 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20  ce Of Data In A 
2c780 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a  Query Result.**.
2c790 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
2c7a0 65 73 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61  es provide a mea
2c7b0 6e 73 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20  ns to determine 
2c7c0 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 61  the database, ta
2c7d0 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c  ble, and.** tabl
2c7e0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73  e column that is
2c7f0 20 74 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61   the origin of a
2c800 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 73 75   particular resu
2c810 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20  lt column in.** 
2c820 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2c830 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  nt..** ^The name
2c840 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2c850 20 6f 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c   or table or col
2c860 75 6d 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72  umn can be retur
2c870 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72  ned as.** either
2c880 20 61 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d   a UTF-8 or UTF-
2c890 31 36 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65  16 string.  ^The
2c8a0 20 5f 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74   _database_ rout
2c8b0 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74  ines return.** t
2c8c0 68 65 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65  he database name
2c8d0 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f  , the _table_ ro
2c8e0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68  utines return th
2c8f0 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e  e table name, an
2c900 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f  d.** the origin_
2c910 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2c920 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65   the column name
2c930 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e  ..** ^The return
2c940 65 64 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c  ed string is val
2c950 69 64 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72  id until the [pr
2c960 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c970 5d 20 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a  ] is destroyed.*
2c980 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
2c990 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2c9a0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2c9b0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2c9c0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2c9d0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2c9e0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2c9f0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2ca00 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2ca10 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61   or until the sa
2ca20 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69  me information i
2ca30 73 20 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61  s requested.** a
2ca40 67 61 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72  gain in a differ
2ca50 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a  ent encoding..**
2ca60 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72  .** ^The names r
2ca70 65 74 75 72 6e 65 64 20 61 72 65 20 74 68 65 20  eturned are the 
2ca80 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61  original un-alia
2ca90 73 65 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  sed names of the
2caa0 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61  .** database, ta
2cab0 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e  ble, and column.
2cac0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  .**.** ^The firs
2cad0 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  t argument to th
2cae0 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 69  ese interfaces i
2caf0 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  s a [prepared st
2cb00 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68  atement]..** ^Th
2cb10 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65  ese functions re
2cb20 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2cb30 20 61 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72   about the Nth r
2cb40 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74  esult column ret
2cb50 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  urned by.** the 
2cb60 73 74 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65  statement, where
2cb70 20 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64   N is the second
2cb80 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
2cb90 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  nt..** ^The left
2cba0 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20  -most column is 
2cbb0 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65  column 0 for the
2cbc0 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
2cbd0 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ** ^If the Nth c
2cbe0 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62  olumn returned b
2cbf0 79 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  y the statement 
2cc00 69 73 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e  is an expression
2cc10 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20   or.** subquery 
2cc20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c  and is not a col
2cc30 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  umn value, then 
2cc40 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e  all of these fun
2cc50 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a  ctions return.**
2cc60 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72   NULL.  ^These r
2cc70 6f 75 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73  outine might als
2cc80 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66  o return NULL if
2cc90 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
2cca0 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63  tion error.** oc
2ccb0 63 75 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73  curs.  ^Otherwis
2ccc0 65 2c 20 74 68 65 79 20 72 65 74 75 72 6e 20 74  e, they return t
2ccd0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61  he name of the a
2cce0 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
2ccf0 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63  , table,.** or c
2cd00 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79  olumn that query
2cd10 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77   result column w
2cd20 61 73 20 65 78 74 72 61 63 74 65 64 20 66 72 6f  as extracted fro
2cd30 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74  m..**.** ^As wit
2cd40 68 20 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69  h all other SQLi
2cd50 74 65 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77  te APIs, those w
2cd60 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77  hose names end w
2cd70 69 74 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a  ith "16" return.
2cd80 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65  ** UTF-16 encode
2cd90 64 20 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68  d strings and th
2cda0 65 20 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e  e other function
2cdb0 73 20 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a  s return UTF-8..
2cdc0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49  **.** ^These API
2cdd0 73 20 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c  s are only avail
2cde0 61 62 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72  able if the libr
2cdf0 61 72 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64  ary was compiled
2ce00 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51   with the.** [SQ
2ce10 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55  LITE_ENABLE_COLU
2ce20 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70  MN_METADATA] C-p
2ce30 72 65 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62  reprocessor symb
2ce40 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f  ol..**.** If two
2ce50 20 6f 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73   or more threads
2ce60 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72   call one or mor
2ce70 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  e of these routi
2ce80 6e 65 73 20 61 67 61 69 6e 73 74 20 74 68 65 20  nes against the 
2ce90 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64  same.** prepared
2cea0 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63   statement and c
2ceb0 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d  olumn at the sam
2cec0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2ced0 72 65 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75  results are.** u
2cee0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2cef0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
2cf00 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
2cf10 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69  or more.** [sqli
2cf20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2cf30 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d  ase_name | colum
2cf40 6e 20 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72  n metadata inter
2cf50 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68  faces].** for th
2cf60 65 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64  e same [prepared
2cf70 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20   statement] and 
2cf80 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a  result column.**
2cf90 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
2cfa0 65 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  e then the resul
2cfb0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2cfc0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
2cfd0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2cfe0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2cff0 61 73 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33  ase_name(sqlite3
2d000 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c  _stmt*,int);.SQL
2d010 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
2d020 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2d030 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2d040 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2d050 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2d060 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
2d070 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62  lite3_column_tab
2d080 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  le_name(sqlite3_
2d090 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2d0a0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2d0b0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2d0c0 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73  n_table_name16(s
2d0d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2d0e0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
2d0f0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2d100 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f  3_column_origin_
2d110 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
2d120 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f  t*,int);.SQLITE_
2d130 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
2d140 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f  sqlite3_column_o
2d150 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c  rigin_name16(sql
2d160 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2d170 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d180 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61 74  : Declared Datat
2d190 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20 52  ype Of A Query R
2d1a0 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  esult.**.** ^(Th
2d1b0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
2d1c0 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  r is a [prepared
2d1d0 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2d1e0 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e  If this statemen
2d1f0 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20  t is a [SELECT] 
2d200 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68  statement and th
2d210 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20  e Nth column of 
2d220 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  the.** returned 
2d230 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68  result set of th
2d240 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61  at [SELECT] is a
2d250 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e   table column (n
2d260 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73  ot an.** express
2d270 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29  ion or subquery)
2d280 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72   then the declar
2d290 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20 74  ed type of the t
2d2a0 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69  able.** column i
2d2b0 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e  s returned.)^  ^
2d2c0 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d  If the Nth colum
2d2d0 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  n of the result 
2d2e0 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70  set is an.** exp
2d2f0 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
2d300 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c  ery, then a NULL
2d310 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75   pointer is retu
2d320 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  rned..** ^The re
2d330 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2d340 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e   always UTF-8 en
2d350 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46  coded..**.** ^(F
2d360 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65  or example, give
2d370 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73  n the database s
2d380 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45  chema:.**.** CRE
2d390 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31 20  ATE TABLE t1(c1 
2d3a0 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20  VARIANT);.**.** 
2d3b0 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  and the followin
2d3c0 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  g statement to b
2d3d0 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a  e compiled:.**.*
2d3e0 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c  * SELECT c1 + 1,
2d3f0 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a   c1 FROM t1;.**.
2d400 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ** this routine 
2d410 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65  would return the
2d420 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54   string "VARIANT
2d430 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64  " for the second
2d440 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d   result.** colum
2d450 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20  n (i==1), and a 
2d460 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72  NULL pointer for
2d470 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75 6c   the first resul
2d480 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e  t column (i==0).
2d490 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  )^.**.** ^SQLite
2d4a0 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75   uses dynamic ru
2d4b0 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20  n-time typing.  
2d4c0 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65  ^So just because
2d4d0 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20   a column.** is 
2d4e0 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74  declared to cont
2d4f0 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ain a particular
2d500 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d   type does not m
2d510 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ean that the.** 
2d520 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74  data stored in t
2d530 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66  hat column is of
2d540 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74 79   the declared ty
2d550 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a  pe.  SQLite is.*
2d560 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64  * strongly typed
2d570 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e 67  , but the typing
2d580 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20   is dynamic not 
2d590 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a  static.  ^Type.*
2d5a0 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20  * is associated 
2d5b0 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20  with individual 
2d5c0 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68  values, not with
2d5d0 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a   the containers.
2d5e0 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ** used to hold 
2d5f0 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f  those values..*/
2d600 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2d610 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2d620 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28  column_decltype(
2d630 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d640 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2d650 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d660 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2d670 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
2d680 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2d690 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
2d6a0 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
2d6b0 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  ent.**.** After 
2d6c0 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2d6d0 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
2d6e0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
2d6f0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2d700 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2d710 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2d720 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
2d730 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
2d740 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
2d750 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2d760 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2d770 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
2d780 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
2d790 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
2d7a0 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
2d7b0 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
2d7c0 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
2d7d0 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
2d7e0 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
2d7f0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
2d800 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
2d810 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
2d820 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2d830 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
2d840 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
2d850 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
2d860 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2d870 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2d880 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2d890 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
2d8a0 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2d8b0 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
2d8c0 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2d8d0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2d8e0 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2d8f0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
2d900 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2d910 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
2d920 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
2d930 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2d940 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
2d950 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
2d960 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
2d970 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2d980 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
2d990 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
2d9a0 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
2d9b0 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
2d9c0 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
2d9d0 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
2d9e0 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
2d9f0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
2da00 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
2da10 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
2da20 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
2da30 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
2da40 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2da50 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
2da60 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
2da70 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
2da80 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
2da90 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
2daa0 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
2dab0 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
2dac0 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
2dad0 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
2dae0 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
2daf0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2db00 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
2db10 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
2db20 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
2db30 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
2db40 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
2db50 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
2db60 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2db70 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
2db80 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
2db90 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
2dba0 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
2dbb0 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
2dbc0 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
2dbd0 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
2dbe0 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
2dbf0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
2dc00 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
2dc10 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2dc20 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
2dc30 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
2dc40 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
2dc50 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2dc60 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2dc70 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
2dc80 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
2dc90 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
2dca0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2dcb0 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2dcc0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2dcd0 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
2dce0 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
2dcf0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
2dd00 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
2dd10 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
2dd20 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
2dd30 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
2dd40 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
2dd50 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
2dd60 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
2dd70 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
2dd80 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
2dd90 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
2dda0 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
2ddb0 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
2ddc0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2ddd0 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
2dde0 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
2ddf0 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
2de00 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
2de10 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
2de20 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
2de30 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
2de40 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
2de50 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
2de60 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
2de70 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
2de80 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
2de90 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
2dea0 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
2deb0 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
2dec0 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
2ded0 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2dee0 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
2def0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
2df00 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
2df10 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2df20 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
2df30 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
2df40 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
2df50 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
2df60 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
2df70 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
2df80 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
2df90 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
2dfa0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2dfb0 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
2dfc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2dfd0 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
2dfe0 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
2dff0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2e000 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
2e010 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
2e020 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2e030 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
2e040 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
2e050 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
2e060 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
2e070 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
2e080 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
2e090 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
2e0a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2e0b0 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
2e0c0 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
2e0d0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2e0e0 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
2e0f0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
2e100 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
2e110 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
2e120 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
2e130 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
2e140 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
2e150 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
2e160 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2e170 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
2e180 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
2e190 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
2e1a0 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
2e1b0 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
2e1c0 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
2e1d0 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
2e1e0 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
2e1f0 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
2e200 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2e210 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
2e220 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2e230 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
2e240 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
2e250 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2e260 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
2e270 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
2e280 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
2e290 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
2e2a0 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
2e2b0 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2e2c0 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
2e2d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2e2e0 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
2e2f0 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
2e300 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
2e310 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2e320 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72  .  But after ver
2e330 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
2e340 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
2e350 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
2e360 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2e370 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
2e380 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
2e390 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
2e3a0 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
2e3b0 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
2e3c0 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
2e3d0 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
2e3e0 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
2e3f0 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
2e400 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
2e410 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
2e420 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
2e430 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
2e440 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
2e450 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
2e460 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
2e470 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
2e480 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2e490 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
2e4a0 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
2e4b0 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
2e4c0 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
2e4d0 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
2e4e0 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
2e4f0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
2e500 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
2e510 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
2e520 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
2e530 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
2e540 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
2e550 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2e560 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
2e570 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
2e580 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
2e590 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2e5a0 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2e5b0 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
2e5c0 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
2e5d0 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
2e5e0 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
2e5f0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
2e600 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
2e610 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
2e620 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
2e630 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
2e640 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
2e650 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
2e660 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2e670 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
2e680 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
2e690 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
2e6a0 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
2e6b0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2e6c0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2e6d0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2e6e0 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
2e6f0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
2e700 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2e710 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e720 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
2e730 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
2e740 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
2e750 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
2e760 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2e770 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
2e780 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
2e790 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
2e7a0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2e7b0 6e 64 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  nded..*/.SQLITE_
2e7c0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2e7d0 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
2e7e0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2e7f0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
2e800 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
2e810 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult set.**.** ^T
2e820 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2e830 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
2e840 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
2e850 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2e860 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
2e870 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2e880 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
2e890 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2e8a0 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
2e8b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2e8c0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
2e8d0 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
2e8e0 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
2e8f0 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
2e900 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
2e910 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e920 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
2e930 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
2e940 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2e950 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
2e960 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2e970 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2e980 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
2e990 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
2e9a0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
2e9b0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2e9c0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2e9d0 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
2e9e0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2e9f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2ea00 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
2ea10 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2ea20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2ea30 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
2ea40 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
2ea50 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
2ea60 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2ea70 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2ea80 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
2ea90 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
2eaa0 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
2eab0 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
2eac0 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
2ead0 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
2eae0 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
2eaf0 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
2eb00 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
2eb10 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
2eb20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
2eb30 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2eb40 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2eb50 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c  _count()].*/.SQL
2eb60 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2eb70 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
2eb80 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
2eb90 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
2eba0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
2ebb0 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
2ebc0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
2ebd0 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
2ebe0 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
2ebf0 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
2ec00 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
2ec10 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
2ec20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
2ec30 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2ec40 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
2ec50 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
2ec60 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
2ec70 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
2ec80 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
2ec90 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
2eca0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
2ecb0 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
2ecc0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
2ecd0 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
2ece0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
2ecf0 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
2ed00 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
2ed10 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
2ed20 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
2ed30 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
2ed40 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
2ed50 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
2ed60 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
2ed70 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
2ed80 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
2ed90 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
2eda0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
2edb0 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
2edc0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
2edd0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
2ede0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2edf0 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
2ee00 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
2ee10 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
2ee20 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
2ee30 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
2ee40 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
2ee50 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
2ee60 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
2ee70 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
2ee80 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
2ee90 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
2eea0 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
2eeb0 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
2eec0 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
2eed0 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
2eee0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
2eef0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2ef00 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
2ef10 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65  t set" interface
2ef20 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
2ef30 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
2ef40 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
2ef50 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
2ef60 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
2ef70 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
2ef80 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
2ef90 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
2efa0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
2efb0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
2efc0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2efd0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
2efe0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
2eff0 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
2f000 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
2f010 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
2f020 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2f030 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2f040 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
2f050 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
2f060 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
2f070 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
2f080 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
2f090 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
2f0a0 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
2f0b0 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
2f0c0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
2f0d0 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
2f0e0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
2f0f0 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2f100 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
2f110 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
2f120 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
2f130 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
2f140 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
2f150 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2f160 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
2f170 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
2f180 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
2f190 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
2f1a0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
2f1b0 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
2f1c0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2f1d0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
2f1e0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
2f1f0 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
2f200 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
2f210 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2f220 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
2f230 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
2f240 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
2f250 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2f260 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
2f270 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
2f280 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
2f290 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
2f2a0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
2f2b0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
2f2c0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
2f2d0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
2f2e0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f2f0 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
2f300 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2f310 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
2f320 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
2f330 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
2f340 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2f350 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2f360 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f370 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
2f380 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
2f390 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
2f3a0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
2f3b0 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
2f3c0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
2f3d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
2f3e0 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
2f3f0 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2f400 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2f410 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f420 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
2f430 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2f440 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
2f450 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
2f460 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
2f470 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
2f480 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
2f490 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
2f4a0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
2f4b0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
2f4c0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
2f4d0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
2f4e0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
2f4f0 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
2f500 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
2f510 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
2f520 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2f530 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2f540 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
2f550 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
2f560 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
2f570 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
2f580 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
2f590 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
2f5a0 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
2f5b0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
2f5c0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2f5d0 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
2f5e0 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
2f5f0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
2f600 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
2f610 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of 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 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
2f640 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
2f650 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
2f660 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
2f670 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
2f680 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
2f690 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f6a0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
2f6b0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
2f6c0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2f6d0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
2f6e0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
2f6f0 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
2f700 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2f710 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f720 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
2f730 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
2f740 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
2f750 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2f760 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2f770 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2f780 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2f790 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2f7a0 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
2f7b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2f7c0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2f7d0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2f7e0 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
2f7f0 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
2f800 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2f810 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
2f820 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2f830 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
2f840 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2f850 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
2f860 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
2f870 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
2f880 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
2f890 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
2f8a0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2f8b0 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
2f8c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2f8d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2f8e0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2f8f0 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2f900 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2f910 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
2f920 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2f930 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
2f940 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2f950 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
2f960 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
2f970 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2f980 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
2f990 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
2f9a0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
2f9b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f9c0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
2f9d0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
2f9e0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
2f9f0 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
2fa00 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
2fa10 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
2fa20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2fa30 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
2fa40 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2fa50 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
2fa60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2fa70 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
2fa80 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
2fa90 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
2faa0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
2fab0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2fac0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
2fad0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
2fae0 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
2faf0 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
2fb00 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
2fb10 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
2fb20 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
2fb30 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
2fb40 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
2fb50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2fb60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2fb70 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2fb80 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
2fb90 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
2fba0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
2fbb0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
2fbc0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
2fbd0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
2fbe0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
2fbf0 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
2fc00 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2fc10 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
2fc20 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
2fc30 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d  are always zero-
2fc40 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
2fc50 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
2fc60 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
2fc70 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
2fc80 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
2fc90 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
2fca0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2fcb0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
2fcc0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
2fcd0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
2fce0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
2fcf0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2fd00 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75  e] object.  An u
2fd10 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2fd20 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a  e3_value object.
2fd30 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ** may only be u
2fd40 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  sed with [sqlite
2fd50 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
2fd60 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
2fd70 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
2fd80 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
2fd90 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2fda0 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
2fdb0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
2fdc0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2fdd0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
2fde0 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
2fdf0 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
2fe00 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
2fe10 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2fe20 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
2fe30 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
2fe40 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
2fe50 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
2fe60 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
2fe70 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
2fe80 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
2fe90 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
2fea0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
2feb0 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
2fec0 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61  te.  ^For.** exa
2fed0 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
2fee0 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
2fef0 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
2ff00 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
2ff10 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
2ff20 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
2ff30 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
2ff40 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
2ff50 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
2ff60 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
2ff70 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
2ff80 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
2ff90 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
2ffa0 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
2ffb0 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
2ffc0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
2ffd0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
2ffe0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
2fff0 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
30000 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
30010 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
30020 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
30030 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
30040 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
30050 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
30060 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
30070 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
30080 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
30090 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
300a0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
300b0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
300c0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
300d0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
300e0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
300f0 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
30100 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
30110 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
30120 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
30130 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
30140 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
30150 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
30160 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
30170 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
30180 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
30190 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
301a0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
301b0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
301c0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
301d0 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
301e0 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
301f0 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
30200 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
30210 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
30220 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
30230 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
30240 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
30250 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
30260 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
30270 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
30280 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
30290 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
302a0 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
302b0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
302c0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
302d0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
302e0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
302f0 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
30300 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
30310 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
30320 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
30330 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
30340 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
30350 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
30360 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
30370 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
30380 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
30390 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
303a0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
303b0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
303c0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
303d0 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
303e0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
303f0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
30400 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
30410 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
30420 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
30430 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
30440 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  )^.**.** The tab
30450 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
30460 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
30470 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
30480 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
30490 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
304a0 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
304b0 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
304c0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
304d0 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
304e0 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
304f0 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
30500 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
30510 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
30520 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
30530 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
30540 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
30550 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
30560 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
30570 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  mmers..**.** Not
30580 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
30590 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
305a0 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
305b0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
305c0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
305d0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
305e0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
305f0 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
30600 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
30610 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
30620 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
30630 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
30640 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
30650 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
30660 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
30670 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
30680 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
30690 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
306a0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
306b0 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
306c0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
306d0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
306e0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
306f0 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
30700 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
30710 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
30720 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
30730 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
30740 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
30750 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
30760 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
30770 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30780 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
30790 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
307a0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
307b0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
307c0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
307d0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
307e0 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
307f0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
30800 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
30810 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
30820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30830 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
30840 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30850 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
30860 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
30870 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
30880 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
30890 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
308a0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
308b0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
308c0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
308d0 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
308e0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
308f0 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
30900 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
30910 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
30920 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
30930 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
30940 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
30950 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
30960 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
30970 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
30980 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
30990 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
309a0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
309b0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
309c0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
309d0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
309e0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
309f0 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
30a00 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
30a10 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
30a20 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
30a30 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
30a40 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
30a50 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
30a60 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
30a70 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
30a80 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
30a90 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
30aa0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
30ab0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
30ac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30ad0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
30ae0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
30af0 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
30b00 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
30b10 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
30b20 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
30b30 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
30b40 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
30b50 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30b60 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
30b70 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
30b80 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
30b90 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
30ba0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
30bb0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
30bc0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
30bd0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30be0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
30bf0 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
30c00 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
30c10 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
30c20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
30c30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
30c40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
30c50 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
30c60 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
30c70 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
30c80 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
30c90 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
30ca0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
30cb0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
30cc0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
30cd0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
30ce0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
30cf0 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
30d00 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
30d10 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
30d20 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
30d30 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
30d40 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
30d50 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
30d60 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
30d70 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
30d80 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
30d90 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
30da0 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
30db0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
30dc0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
30dd0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
30de0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
30df0 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
30e00 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
30e10 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
30e20 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
30e30 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
30e40 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
30e50 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
30e60 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
30e70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
30e80 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
30e90 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30ea0 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
30eb0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
30ec0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
30ed0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
30ee0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
30ef0 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
30f00 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
30f10 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
30f20 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
30f30 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
30f40 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
30f50 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
30f60 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
30f70 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
30f80 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
30f90 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
30fa0 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
30fb0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
30fc0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
30fd0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
30fe0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
30ff0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  /.SQLITE_API con
31000 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
31010 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
31020 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
31030 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
31040 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
31050 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
31060 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31070 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
31080 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
31090 6d 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74  mn_bytes16(sqlit
310a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
310b0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
310c0 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63  double sqlite3_c
310d0 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c  olumn_double(sql
310e0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
310f0 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
31100 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  I int sqlite3_co
31110 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33  lumn_int(sqlite3
31120 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
31130 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  );.SQLITE_API sq
31140 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
31150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34  te3_column_int64
31160 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31170 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
31180 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69  E_API const unsi
31190 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
311a0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73  e3_column_text(s
311b0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
311c0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
311d0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
311e0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
311f0 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ext16(sqlite3_st
31200 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
31210 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
31220 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
31230 70 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  pe(sqlite3_stmt*
31240 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
31250 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
31260 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
31270 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
31280 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
31290 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
312a0 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
312b0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
312c0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
312d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
312e0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
312f0 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
31300 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
31310 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
31320 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
31330 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
31340 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
31350 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
31360 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
31370 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
31380 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
31390 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
313a0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
313b0 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
313c0 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
313d0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
313e0 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
313f0 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
31400 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
31410 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
31420 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
31430 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
31440 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
31450 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
31460 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
31470 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
31480 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
31490 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
314a0 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
314b0 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
314c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
314d0 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
314e0 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
314f0 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
31500 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
31510 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
31520 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
31530 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
31540 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
31550 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
31560 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
31570 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
31580 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
31590 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
315a0 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
315b0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
315c0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
315d0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
315e0 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
315f0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
31600 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
31610 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31620 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
31630 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
31640 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
31650 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
31660 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
31670 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
31680 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
31690 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
316a0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
316b0 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
316c0 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
316d0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
316e0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
316f0 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
31700 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
31710 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
31720 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
31730 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
31740 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
31750 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
31760 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
31770 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
31780 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
31790 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
317a0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
317b0 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
317c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
317d0 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
317e0 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
317f0 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
31800 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
31810 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
31820 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
31830 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
31840 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
31850 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
31860 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
31870 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
31880 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
31890 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
318a0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
318b0 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
318c0 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
318d0 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
318e0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
318f0 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
31900 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
31910 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
31920 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
31930 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
31940 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31950 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
31960 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
31970 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
31980 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
31990 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
319a0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
319b0 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
319c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
319d0 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
319e0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
319f0 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
31a00 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
31a10 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
31a20 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
31a30 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
31a40 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
31a50 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
31a60 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
31a70 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
31a80 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
31a90 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
31aa0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
31ab0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
31ac0 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
31ad0 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
31ae0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
31af0 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
31b00 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
31b10 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
31b20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
31b30 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
31b40 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
31b50 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
31b60 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
31b70 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
31b80 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
31b90 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
31ba0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
31bb0 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73   sqlite3_reset(s
31bc0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
31bd0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
31be0 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20  3REF: Create Or 
31bf0 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e  Redefine SQL Fun
31c00 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52  ctions.** KEYWOR
31c10 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72  DS: {function cr
31c20 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d  eation routines}
31c30 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
31c40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31c50 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d  ed SQL function}
31c60 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61  .** KEYWORDS: {a
31c70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31c80 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
31c90 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66  }.**.** ^These f
31ca0 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63  unctions (collec
31cb0 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  tively known as 
31cc0 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69  "function creati
31cd0 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a  on routines").**
31ce0 20 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64   are used to add
31cf0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f   SQL functions o
31d00 72 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20  r aggregates or 
31d10 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20  to redefine the 
31d20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65  behavior.** of e
31d30 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63  xisting SQL func
31d40 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
31d50 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64  tes.  The only d
31d60 69 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65  ifferences betwe
31d70 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74  en.** these rout
31d80 69 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78  ines are the tex
31d90 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63  t encoding expec
31da0 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73  ted for.** the s
31db0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
31dc0 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65  (the name of the
31dd0 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20   function being 
31de0 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20  created).** and 
31df0 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20  the presence or 
31e00 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73  absence of a des
31e10 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b  tructor callback
31e20 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c   for.** the appl
31e30 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
31e40 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
31e50 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
31e60 20 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73   is the [databas
31e70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f  e connection] to
31e80 20 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a   which the SQL.*
31e90 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f  * function is to
31ea0 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20   be added.  ^If 
31eb0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
31ec0 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  ses more than on
31ed0 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
31ee0 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70  nnection then ap
31ef0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
31f00 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  d SQL functions 
31f10 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a  must be added.**
31f20 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73   to each databas
31f30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70  e connection sep
31f40 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  arately..**.** ^
31f50 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
31f60 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
31f70 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63   of the SQL func
31f80 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74  tion to be creat
31f90 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e  ed or.** redefin
31fa0 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68  ed.  ^The length
31fb0 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20   of the name is 
31fc0 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62  limited to 255 b
31fd0 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a  ytes in a UTF-8.
31fe0 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ** representatio
31ff0 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20  n, exclusive of 
32000 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
32010 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74  tor.  ^Note that
32020 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e   the name.** len
32030 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20  gth limit is in 
32040 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74  UTF-8 bytes, not
32050 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20   characters nor 
32060 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a  UTF-16 bytes.  .
32070 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20  ** ^Any attempt 
32080 74 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63  to create a func
32090 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67  tion with a long
320a0 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20  er name.** will 
320b0 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54  result in [SQLIT
320c0 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20  E_MISUSE] being 
320d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
320e0 5e 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  ^The third param
320f0 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69  eter (nArg).** i
32100 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
32110 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74  arguments that t
32120 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  he SQL function 
32130 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20  or.** aggregate 
32140 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20  takes. ^If this 
32150 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c  parameter is -1,
32160 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75   then the SQL fu
32170 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
32180 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20  regate may take 
32190 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  any number of ar
321a0 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20  guments between 
321b0 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a  0 and the limit.
321c0 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74  ** set by [sqlit
321d0 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54  e3_limit]([SQLIT
321e0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
321f0 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20  _ARG]).  If the 
32200 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
32210 65 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  er is less than 
32220 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  -1 or greater th
32230 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20  an 127 then the 
32240 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75  behavior is.** u
32250 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
32260 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
32270 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c  meter, eTextRep,
32280 20 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a   specifies what.
32290 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20  ** [SQLITE_UTF8 
322a0 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d  | text encoding]
322b0 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69   this SQL functi
322c0 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a  on prefers for.*
322d0 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73  * its parameters
322e0 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e  .  Every SQL fun
322f0 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61  ction implementa
32300 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c  tion must be abl
32310 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
32320 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c  h UTF-8, UTF-16l
32330 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20  e, or UTF-16be. 
32340 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d   But some implem
32350 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65  entations may be
32360 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65  .** more efficie
32370 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f  nt with one enco
32380 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65  ding than anothe
32390 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74  r.  ^An applicat
323a0 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b  ion may.** invok
323b0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
323c0 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73  _function() or s
323d0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
323e0 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69  nction16() multi
323f0 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74  ple.** times wit
32400 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  h the same funct
32410 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66  ion but with dif
32420 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66  ferent values of
32430 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57   eTextRep..** ^W
32440 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70  hen multiple imp
32450 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
32460 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
32470 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c  n are available,
32480 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20   SQLite.** will 
32490 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61  pick the one tha
324a0 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c  t involves the l
324b0 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
324c0 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a  ata conversion..
324d0 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f  ** If there is o
324e0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70  nly a single imp
324f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63  lementation whic
32500 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  h does not care 
32510 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63  what text.** enc
32520 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74  oding is used, t
32530 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61  hen the fourth a
32540 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
32550 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a  e [SQLITE_ANY]..
32560 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74  **.** ^(The fift
32570 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  h parameter is a
32580 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e  n arbitrary poin
32590 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d  ter.  The implem
325a0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a  entation of the.
325b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20  ** function can 
325c0 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74  gain access to t
325d0 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e  his pointer usin
325e0 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  g [sqlite3_user_
325f0 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  data()].)^.**.**
32600 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76   ^The sixth, sev
32610 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20  enth and eighth 
32620 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e  parameters, xFun
32630 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  c, xStep and xFi
32640 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e  nal, are.** poin
32650 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61  ters to C-langua
32660 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ge functions tha
32670 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20  t implement the 
32680 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a  SQL function or.
32690 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41  ** aggregate. ^A
326a0 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63   scalar SQL func
326b0 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e  tion requires an
326c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
326d0 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20  of the xFunc.** 
326e0 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e  callback only; N
326f0 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73  ULL pointers mus
32700 74 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  t be passed as t
32710 68 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69  he xStep and xFi
32720 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  nal.** parameter
32730 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65  s. ^An aggregate
32740 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65   SQL function re
32750 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d  quires an implem
32760 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65  entation of xSte
32770 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20  p.** and xFinal 
32780 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  and NULL pointer
32790 20 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20   must be passed 
327a0 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64  for xFunc. ^To d
327b0 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e  elete an existin
327c0 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f  g.** SQL functio
327d0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20  n or aggregate, 
327e0 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  pass NULL pointe
327f0 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65  rs for all three
32800 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c   function.** cal
32810 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  lbacks..**.** ^(
32820 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72  If the ninth par
32830 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
32840 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
32850 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55  n_v2() is not NU
32860 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69  LL,.** then it i
32870 73 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72  s destructor for
32880 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
32890 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a   data pointer. .
328a0 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  ** The destructo
328b0 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65  r is invoked whe
328c0 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  n the function i
328d0 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65  s deleted, eithe
328e0 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76  r by being.** ov
328f0 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e  erloaded or when
32900 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
32910 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e  nnection closes.
32920 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72  )^.** ^The destr
32930 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e  uctor is also in
32940 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c  voked if the cal
32950 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  l to.** sqlite3_
32960 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
32970 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e  v2() fails..** ^
32980 57 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63  When the destruc
32990 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20  tor callback of 
329a0 74 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65  the tenth parame
329b0 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20  ter is invoked, 
329c0 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  it.** is passed 
329d0 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
329e0 74 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70  t which is a cop
329f0 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  y of the applica
32a00 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f  tion data .** po
32a10 69 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20  inter which was 
32a20 74 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  the fifth parame
32a30 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ter to sqlite3_c
32a40 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
32a50 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69  2()..**.** ^It i
32a60 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72  s permitted to r
32a70 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65  egister multiple
32a80 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
32a90 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   of the same.** 
32aa0 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74  functions with t
32ab0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74  he same name but
32ac0 20 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66   with either dif
32ad0 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f  fering numbers o
32ae0 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f  f.** arguments o
32af0 72 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66  r differing pref
32b00 65 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64  erred text encod
32b10 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77  ings.  ^SQLite w
32b20 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69  ill use.** the i
32b30 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68  mplementation th
32b40 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20  at most closely 
32b50 6d 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20  matches the way 
32b60 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20  in which the.** 
32b70 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
32b80 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69  used.  ^A functi
32b90 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  on implementatio
32ba0 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67  n with a non-neg
32bb0 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61  ative.** nArg pa
32bc0 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74  rameter is a bet
32bd0 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ter match than a
32be0 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d   function implem
32bf0 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a  entation with.**
32c00 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67   a negative nArg
32c10 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  .  ^A function w
32c20 68 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72  here the preferr
32c30 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ed text encoding
32c40 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20  .** matches the 
32c50 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e  database encodin
32c60 67 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a  g is a better.**
32c70 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75   match than a fu
32c80 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
32c90 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66   encoding is dif
32ca0 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20  ferent.  .** ^A 
32cb0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
32cc0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
32cd0 65 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65  erence is betwee
32ce0 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54  n UTF16le and UT
32cf0 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c  F16be.** is a cl
32d00 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20  oser match than 
32d10 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  a function where
32d20 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
32d30 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62  fference is.** b
32d40 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20  etween UTF8 and 
32d50 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75  UTF16..**.** ^Bu
32d60 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73  ilt-in functions
32d70 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64   may be overload
32d80 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63  ed by new applic
32d90 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
32da0 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  nctions..**.** ^
32db0 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  An application-d
32dc0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
32dd0 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20  is permitted to 
32de0 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51  call other.** SQ
32df0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e  Lite interfaces.
32e00 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20    However, such 
32e10 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a  calls must not.*
32e20 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  * close the data
32e30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
32e40 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20  nor finalize or 
32e50 72 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72  reset the prepar
32e60 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
32e70 69 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e  in which the fun
32e80 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
32e90 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
32ea0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
32eb0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
32ec0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
32ed0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
32ee0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
32ef0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
32f00 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
32f10 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
32f20 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
32f30 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
32f40 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
32f50 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
32f60 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
32f70 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
32f80 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
32f90 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
32fa0 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  t*).);.SQLITE_AP
32fb0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
32fc0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
32fd0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
32fe0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
32ff0 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
33000 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
33010 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
33020 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
33030 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
33040 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
33050 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
33060 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
33070 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
33080 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
33090 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
330a0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
330b0 6e 74 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54  ntext*).);.SQLIT
330c0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
330d0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
330e0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  n_v2(.  sqlite3 
330f0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61  *db,.  const cha
33100 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  r *zFunctionName
33110 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
33120 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
33130 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
33140 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
33150 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
33160 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
33170 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
33180 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
33190 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
331a0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
331b0 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
331c0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20  e3_context*),.  
331d0 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
331e0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
331f0 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74 20   CAPI3REF: Text 
33200 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20  Encodings.**.** 
33210 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64  These constant d
33220 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f  efine integer co
33230 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73 65  des that represe
33240 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a  nt the various.*
33250 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73  * text encodings
33260 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
33270 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  Lite..*/.#define
33280 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20   SQLITE_UTF8    
33290 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
332a0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20   SQLITE_UTF16LE 
332b0 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
332c0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20   SQLITE_UTF16BE 
332d0 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
332e0 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20   SQLITE_UTF16   
332f0 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55         4    /* U
33300 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  se native byte o
33310 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rder */.#define 
33320 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20  SQLITE_ANY      
33330 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71        5    /* sq
33340 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33350 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64  ction only */.#d
33360 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
33370 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20  16_ALIGNED  8   
33380 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61   /* sqlite3_crea
33390 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c  te_collation onl
333a0 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  y */../*.** CAPI
333b0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
333c0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
333d0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
333e0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
333f0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
33400 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
33410 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
33420 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
33430 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
33440 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
33450 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
33460 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
33470 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
33480 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
33490 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
334a0 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
334b0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
334c0 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
334d0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
334e0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
334f0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
33500 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
33510 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
33520 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
33530 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
33540 44 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c  D.SQLITE_API SQL
33550 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
33560 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
33570 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
33580 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
33590 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f  LITE_API SQLITE_
335a0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
335b0 71 6c 69 74 65 33 5f 65 78 70 69 72 65 64 28 73  qlite3_expired(s
335c0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53  qlite3_stmt*);.S
335d0 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45  QLITE_API SQLITE
335e0 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
335f0 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
33600 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
33610 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
33620 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
33630 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45  API SQLITE_DEPRE
33640 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
33650 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72  3_global_recover
33660 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
33670 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
33680 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65  ATED void sqlite
33690 33 5f 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70  3_thread_cleanup
336a0 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
336b0 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43  PI SQLITE_DEPREC
336c0 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
336d0 5f 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f  _memory_alarm(vo
336e0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
336f0 74 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76  te3_int64,int),v
33700 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
33710 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
33720 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
33730 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
33740 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
33750 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  lues.**.** The C
33760 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
33770 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
33780 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
33790 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
337a0 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
337b0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
337c0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
337d0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
337e0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
337f0 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
33800 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
33810 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
33820 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
33830 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
33840 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
33850 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
33860 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
33870 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
33880 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
33890 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
338a0 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
338b0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
338c0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
338d0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
338e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
338f0 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
33900 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
33910 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
33920 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
33930 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
33940 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
33950 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33960 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
33970 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
33980 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
33990 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
339a0 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
339b0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
339c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
339d0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
339e0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
339f0 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
33a00 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
33a10 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
33a20 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
33a30 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
33a40 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
33a50 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
33a60 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
33a70 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
33a80 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
33a90 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
33aa0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
33ab0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
33ac0 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
33ad0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
33ae0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
33af0 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
33b00 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
33b10 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
33b20 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
33b30 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
33b40 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
33b50 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
33b60 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
33b70 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
33b80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
33b90 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
33ba0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
33bb0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
33bc0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
33bd0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
33be0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
33bf0 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
33c00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
33c10 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
33c20 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
33c30 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
33c40 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
33c50 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
33c60 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
33c70 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
33c80 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
33c90 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
33ca0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
33cb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
33cc0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
33cd0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
33ce0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
33cf0 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
33d00 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
33d10 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
33d20 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
33d30 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
33d40 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
33d50 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
33d60 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
33d70 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
33d80 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
33d90 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
33da0 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
33db0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
33dc0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
33dd0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
33de0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
33df0 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
33e00 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
33e10 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
33e20 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
33e30 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
33e40 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
33e50 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
33e60 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
33e70 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
33e80 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
33e90 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
33ea0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
33eb0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
33ec0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
33ed0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
33ee0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
33ef0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
33f00 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
33f10 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
33f20 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
33f30 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
33f40 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
33f50 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
33f60 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
33f70 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
33f80 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
33f90 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
33fa0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
33fb0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
33fc0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
33fd0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
33fe0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
33ff0 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
34000 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
34010 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51  arameters..*/.SQ
34020 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76  LITE_API const v
34030 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
34040 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
34050 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
34060 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34070 76 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69  value_bytes(sqli
34080 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
34090 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
340a0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
340b0 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
340c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f  );.SQLITE_API do
340d0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
340e0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
340f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34100 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
34110 33 5f 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69  3_value_int(sqli
34120 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
34130 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
34140 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
34150 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
34160 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34170 45 5f 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69  E_API const unsi
34180 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74  gned char *sqlit
34190 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71  e3_value_text(sq
341a0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
341b0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
341c0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
341d0 6c 75 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74  lue_text16(sqlit
341e0 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49  e3_value*);.SQLI
341f0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
34200 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
34210 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65  _text16le(sqlite
34220 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34230 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
34240 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
34250 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65 33  text16be(sqlite3
34260 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
34270 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
34280 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69  _value_type(sqli
34290 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
342a0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
342b0 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69  te3_value_numeri
342c0 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76  c_type(sqlite3_v
342d0 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  alue*);../*.** C
342e0 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
342f0 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74 69  Aggregate Functi
34300 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a  on Context.**.**
34310 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   Implementations
34320 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53 51   of aggregate SQ
34330 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20  L functions use 
34340 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
34350 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
34360 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74  ry for storing t
34370 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  heir state..**.*
34380 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
34390 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67  e the sqlite3_ag
343a0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
343b0 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20  C,N) routine is 
343c0 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61  called .** for a
343d0 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67 72   particular aggr
343e0 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20  egate function, 
343f0 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61  SQLite.** alloca
34400 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c  tes N of memory,
34410 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74   zeroes out that
34420 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74   memory, and ret
34430 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  urns a pointer.*
34440 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d  * to the new mem
34450 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20  ory. ^On second 
34460 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 63  and subsequent c
34470 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
34480 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
34490 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20 73  text() for the s
344a0 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66 75  ame aggregate fu
344b0 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c  nction instance,
344c0 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66  .** the same buf
344d0 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  fer is returned.
344e0 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67    Sqlite3_aggreg
344f0 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73  ate_context() is
34500 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c   normally.** cal
34510 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63  led once for eac
34520 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20  h invocation of 
34530 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61  the xStep callba
34540 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a  ck and then one.
34550 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65  ** last time whe
34560 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
34570 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
34580 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77  .  ^(When no row
34590 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67  s match.** an ag
345a0 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20 74  gregate query, t
345b0 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62  he xStep() callb
345c0 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65  ack of the aggre
345d0 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  gate function.**
345e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
345f0 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20  is never called 
34600 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20  and xFinal() is 
34610 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f  called exactly o
34620 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65  nce..** In those
34630 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f   cases, sqlite3_
34640 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
34650 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c  t() might be cal
34660 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66  led for the.** f
34670 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77  irst time from w
34680 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29  ithin xFinal().)
34690 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
346a0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
346b0 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
346c0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55  ine returns a NU
346d0 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20  LL pointer if N 
346e0 69 73 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20  is.** less than 
346f0 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
34700 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20   or if a memory 
34710 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f  allocate error o
34720 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ccurs..**.** ^(T
34730 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61  he amount of spa
34740 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ce allocated by 
34750 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34760 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69  e_context(C,N) i
34770 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20  s.** determined 
34780 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74  by the N paramet
34790 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63  er on first succ
347a0 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68  essful call.  Ch
347b0 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61  anging the.** va
347c0 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73  lue of N in subs
347d0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
347e0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
347f0 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69  _context() withi
34800 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67  n.** the same ag
34810 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e  gregate function
34820 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e   instance will n
34830 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65  ot resize the me
34840 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69  mory.** allocati
34850 6f 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  on.)^.**.** ^SQL
34860 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
34870 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
34880 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
34890 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
348a0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
348b0 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
348c0 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
348d0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
348e0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
348f0 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
34900 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
34910 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
34920 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
34930 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
34940 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
34950 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
34960 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
34970 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
34980 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
34990 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
349a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
349b0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
349c0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
349d0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
349e0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
349f0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
34a00 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53  is running..*/.S
34a10 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
34a20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34a30 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
34a40 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
34a50 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
34a60 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
34a70 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
34a80 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
34a90 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
34aa0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
34ab0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
34ac0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
34ad0 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
34ae0 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
34af0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
34b00 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
34b10 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34b20 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
34b30 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
34b40 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
34b50 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
34b60 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
34b70 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
34b80 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
34b90 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
34ba0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
34bb0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
34bc0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
34bd0 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
34be0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34bf0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
34c00 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ing..*/.SQLITE_A
34c10 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
34c20 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74  _user_data(sqlit
34c30 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f  e3_context*);../
34c40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
34c50 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
34c60 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73  on For Functions
34c70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34c80 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68  te3_context_db_h
34c90 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63  andle() interfac
34ca0 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79  e returns a copy
34cb0 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74   of.** the point
34cc0 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62  er to the [datab
34cd0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34ce0 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74  (the 1st paramet
34cf0 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73  er).** of the [s
34d00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
34d10 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64  nction()].** and
34d20 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
34d30 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72  _function16()] r
34d40 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69  outines that ori
34d50 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73  ginally.** regis
34d60 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63  tered the applic
34d70 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75  ation defined fu
34d80 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  nction..*/.SQLIT
34d90 45 5f 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73  E_API sqlite3 *s
34da0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64  qlite3_context_d
34db0 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33  b_handle(sqlite3
34dc0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
34dd0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
34de0 63 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20  ction Auxiliary 
34df0 44 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66  Data.**.** The f
34e00 6f 6c 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e  ollowing two fun
34e10 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
34e20 65 64 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c  ed by scalar SQL
34e30 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a   functions to.**
34e40 20 61 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64   associate metad
34e50 61 74 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e  ata with argumen
34e60 74 20 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65  t values. If the
34e70 20 73 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70   same value is p
34e80 61 73 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74  assed to.** mult
34e90 69 70 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73  iple invocations
34ea0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c   of the same SQL
34eb0 20 66 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67   function during
34ec0 20 71 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e   query execution
34ed0 2c 20 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20  , under.** some 
34ee0 63 69 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68  circumstances th
34ef0 65 20 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74  e associated met
34f00 61 64 61 74 61 20 6d 61 79 20 62 65 20 70 72 65  adata may be pre
34f10 73 65 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79  served. This may
34f20 0a 2a 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72  .** be used, for
34f30 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64   example, to add
34f40 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65   a regular-expre
34f50 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73  ssion matching s
34f60 63 61 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  calar.** functio
34f70 6e 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20  n. The compiled 
34f80 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72  version of the r
34f90 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
34fa0 6e 20 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a  n is stored as.*
34fb0 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
34fc0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 53  iated with the S
34fd0 51 4c 20 76 61 6c 75 65 20 70 61 73 73 65 64 20  QL value passed 
34fe0 61 73 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  as the regular e
34ff0 78 70 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74  xpression.** pat
35000 74 65 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69  tern.  The compi
35010 6c 65 64 20 72 65 67 75 6c 61 72 20 65 78 70 72  led regular expr
35020 65 73 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65  ession can be re
35030 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65  used on multiple
35040 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20  .** invocations 
35050 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63  of the same func
35060 74 69 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65  tion so that the
35070 20 6f 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72   original patter
35080 6e 20 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73  n string.** does
35090 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
350a0 72 65 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61  recompiled on ea
350b0 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a  ch invocation..*
350c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
350d0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
350e0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
350f0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
35100 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  he metadata.** a
35110 73 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65  ssociated by the
35120 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
35130 64 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20  data() function 
35140 77 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67  with the Nth arg
35150 75 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74  ument.** value t
35160 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
35170 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35180 6f 6e 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64  on. ^If no metad
35190 61 74 61 20 68 61 73 20 62 65 65 6e 20 65 76 65  ata has been eve
351a0 72 0a 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f  r.** been set fo
351b0 72 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65  r the Nth argume
351c0 6e 74 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69  nt of the functi
351d0 6f 6e 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f  on, or if the co
351e0 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66  rresponding.** f
351f0 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65  unction paramete
35200 72 20 68 61 73 20 63 68 61 6e 67 65 64 20 73 69  r has changed si
35210 6e 63 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74  nce the meta-dat
35220 61 20 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68  a was set,.** th
35230 65 6e 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  en sqlite3_get_a
35240 75 78 64 61 74 61 28 29 20 72 65 74 75 72 6e 73  uxdata() returns
35250 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
35260 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35270 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
35280 29 20 69 6e 74 65 72 66 61 63 65 20 73 61 76 65  ) interface save
35290 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a  s the metadata.*
352a0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
352b0 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
352c0 72 20 61 73 20 74 68 65 20 6d 65 74 61 64 61 74  r as the metadat
352d0 61 20 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a  a for the N-th.*
352e0 2a 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  * argument of th
352f0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
35300 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
35310 20 53 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63   Subsequent.** c
35320 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
35330 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69  get_auxdata() mi
35340 67 68 74 20 72 65 74 75 72 6e 20 74 68 69 73 20  ght return this 
35350 64 61 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a  data, if it has.
35360 2a 2a 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74  ** not been dest
35370 72 6f 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74  royed..** ^If it
35380 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51   is not NULL, SQ
35390 4c 69 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65  Lite will invoke
353a0 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a   the destructor.
353b0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65  ** function give
353c0 6e 20 62 79 20 74 68 65 20 34 74 68 20 70 61 72  n by the 4th par
353d0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
353e0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
353f0 6f 6e 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61  on.** the metada
35400 74 61 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72  ta when the corr
35410 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69  esponding functi
35420 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61  on parameter cha
35430 6e 67 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20  nges.** or when 
35440 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
35450 74 20 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69  t completes, whi
35460 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
35470 73 74 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  st..**.** SQLite
35480 20 69 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c   is free to call
35490 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
354a0 61 6e 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74  and drop metadat
354b0 61 20 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61  a on any.** para
354c0 6d 65 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e  meter of any fun
354d0 63 74 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d  ction at any tim
354e0 65 2e 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75  e.  ^The only gu
354f0 61 72 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a  arantee is that.
35500 2a 2a 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  ** the destructo
35510 72 20 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64  r will be called
35520 20 62 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61   before the meta
35530 64 61 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e  data is dropped.
35540 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63  .**.** ^(In prac
35550 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69  tice, metadata i
35560 73 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77  s preserved betw
35570 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  een function cal
35580 6c 73 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73  ls for.** expres
35590 73 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63  sions that are c
355a0 6f 6e 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69  onstant at compi
355b0 6c 65 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e  le time. This in
355c0 63 6c 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a  cludes literal.*
355d0 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61  * values and [pa
355e0 72 61 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a  rameters].)^.**.
355f0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
35600 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  s must be called
35610 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
35620 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
35630 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  * the SQL functi
35640 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a  on is running..*
35650 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
35660 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
35670 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
35680 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
35690 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
356a0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
356b0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
356c0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
356d0 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
356e0 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
356f0 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
35700 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
35710 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
35720 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
35730 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
35740 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
35750 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
35760 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
35770 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
35780 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
35790 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
357a0 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
357b0 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
357c0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
357d0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
357e0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
357f0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
35800 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
35810 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
35820 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
35830 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
35840 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
35850 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
35860 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
35870 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
35880 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
35890 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
358a0 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
358b0 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
358c0 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
358d0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
358e0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
358f0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
35900 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
35910 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
35920 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
35930 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
35940 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
35950 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
35960 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
35970 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
35980 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
35990 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
359a0 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
359b0 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
359c0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
359d0 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
359e0 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
359f0 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
35a00 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
35a10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
35a20 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
35a30 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
35a40 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
35a50 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
35a60 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
35a70 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
35a80 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
35a90 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
35aa0 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
35ab0 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
35ac0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35ad0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
35ae0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
35af0 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
35b00 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
35b10 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
35b20 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
35b30 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
35b40 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
35b50 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
35b60 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
35b70 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
35b80 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
35b90 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
35ba0 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
35bb0 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
35bc0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
35bd0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
35be0 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
35bf0 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
35c00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
35c10 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
35c20 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
35c30 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
35c40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35c50 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
35c60 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
35c70 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
35c80 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
35c90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
35ca0 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
35cb0 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
35cc0 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
35cd0 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
35ce0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35cf0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
35d00 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
35d10 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
35d20 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
35d30 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
35d40 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
35d50 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
35d60 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
35d70 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
35d80 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
35d90 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
35da0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
35db0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35dc0 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
35dd0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35de0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
35df0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
35e00 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
35e10 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
35e20 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
35e30 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
35e40 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
35e50 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
35e60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35e70 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
35e80 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35e90 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
35ea0 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
35eb0 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
35ec0 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
35ed0 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
35ee0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
35ef0 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
35f00 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
35f10 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
35f20 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
35f30 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
35f40 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
35f50 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
35f60 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
35f70 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
35f80 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
35f90 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
35fa0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
35fb0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
35fc0 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
35fd0 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
35fe0 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
35ff0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36000 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
36010 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
36020 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
36030 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
36040 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
36050 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
36060 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
36070 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
36080 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
36090 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
360a0 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
360b0 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
360c0 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
360d0 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
360e0 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
360f0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
36100 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36110 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
36120 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36130 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
36140 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
36150 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
36160 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
36170 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
36180 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
36190 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
361a0 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
361b0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
361c0 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
361d0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
361e0 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
361f0 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
36200 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
36210 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
36220 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
36230 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
36240 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
36250 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
36260 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
36270 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
36280 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
36290 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
362a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
362b0 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
362c0 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
362d0 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
362e0 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
362f0 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
36300 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
36310 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
36320 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
36330 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
36340 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
36350 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
36360 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36370 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
36380 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
36390 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
363a0 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
363b0 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
363c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
363d0 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e  sult_toobig() in
363e0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
363f0 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
36400 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
36410 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
36420 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
36430 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
36440 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
36450 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36460 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
36470 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
36480 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
36490 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
364a0 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
364b0 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
364c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
364d0 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
364e0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
364f0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
36500 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
36510 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36520 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
36530 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
36540 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
36550 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
36560 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
36570 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
36580 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
36590 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
365a0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
365b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
365c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
365d0 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
365e0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
365f0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
36600 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
36610 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
36620 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36630 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
36640 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
36650 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
36660 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
36670 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
36680 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
36690 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
366a0 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
366b0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
366c0 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
366d0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
366e0 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
366f0 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
36700 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
36710 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
36720 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
36730 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
36740 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
36750 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
36760 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
36770 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
36780 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
36790 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
367a0 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
367b0 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
367c0 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
367d0 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ely..** ^SQLite 
367e0 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
367f0 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
36800 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
36810 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
36820 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
36830 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
36840 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
36850 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
36860 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
36870 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
36880 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
36890 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
368a0 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
368b0 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
368c0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
368d0 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
368e0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
368f0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
36900 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
36910 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
36920 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
36930 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
36940 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
36950 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
36960 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
36970 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
36980 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
36990 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
369a0 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
369b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
369c0 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
369d0 65 73 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33  esult.  If the 3
369e0 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
369f0 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
36a00 65 6e 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65  en it.** must be
36a10 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
36a20 20 69 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67   into the string
36a30 20 77 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74   where the NUL t
36a40 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a  erminator would.
36a50 2a 2a 20 61 70 70 65 61 72 20 69 66 20 74 68 65  ** appear if the
36a60 20 73 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55   string where NU
36a70 4c 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49  L terminated.  I
36a80 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63  f any NUL charac
36a90 74 65 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e  ters occur.** in
36aa0 20 74 68 65 20 73 74 72 69 6e 67 20 61 74 20 61   the string at a
36ab0 20 62 79 74 65 20 6f 66 66 73 65 74 20 74 68 61   byte offset tha
36ac0 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74  t is less than t
36ad0 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
36ae0 33 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  3rd.** parameter
36af0 2c 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  , then the resul
36b00 74 69 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c  ting string will
36b10 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
36b20 64 20 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a  d NULs and the.*
36b30 2a 20 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72  * result of expr
36b40 65 73 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e  essions operatin
36b50 67 20 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74  g on strings wit
36b60 68 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  h embedded NULs 
36b70 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
36b80 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
36b90 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
36ba0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36bb0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
36bc0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
36bd0 6c 74 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e  lt_blob is a non
36be0 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74  -NULL pointer, t
36bf0 68 65 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73  hen SQLite calls
36c00 20 74 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f   that.** functio
36c10 6e 20 61 73 20 74 68 65 20 64 65 73 74 72 75 63  n as the destruc
36c20 74 6f 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20  tor on the text 
36c30 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77  or BLOB result w
36c40 68 65 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69  hen it has.** fi
36c50 6e 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61  nished using tha
36c60 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66  t result..** ^If
36c70 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74   the 4th paramet
36c80 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
36c90 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
36ca0 6e 74 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a  nterfaces or to.
36cb0 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
36cc0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
36cd0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
36ce0 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68  QLITE_STATIC, th
36cf0 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73  en SQLite.** ass
36d00 75 6d 65 73 20 74 68 61 74 20 74 68 65 20 74 65  umes that the te
36d10 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c  xt or BLOB resul
36d20 74 20 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74  t is in constant
36d30 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
36d40 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20  not.** copy the 
36d50 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70  content of the p
36d60 61 72 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c  arameter nor cal
36d70 6c 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f  l a destructor o
36d80 6e 20 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a  n the content.**
36d90 20 77 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e   when it has fin
36da0 69 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74  ished using that
36db0 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20   result..** ^If 
36dc0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
36dd0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
36de0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
36df0 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
36e00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36e10 6f 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61  ob is the specia
36e20 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54  l constant SQLIT
36e30 45 5f 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74  E_TRANSIENT.** t
36e40 68 65 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  hen SQLite makes
36e50 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72   a copy of the r
36e60 65 73 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65  esult into space
36e70 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a   obtained from.*
36e80 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
36e90 6d 61 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65  malloc()] before
36ea0 20 69 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a   it returns..**.
36eb0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36ec0 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69  result_value() i
36ed0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
36ee0 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74  e result of.** t
36ef0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
36f00 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
36f10 74 6f 20 62 65 20 61 20 63 6f 70 79 20 74 68 65  to be a copy the
36f20 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64  .** [unprotected
36f30 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
36f40 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 64  object specified
36f50 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72 61   by the 2nd para
36f60 6d 65 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20  meter.  ^The.** 
36f70 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
36f80 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63 65  alue() interface
36f90 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
36fa0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
36fb0 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20  lue].** so that 
36fc0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
36fd0 75 65 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e  ue] specified in
36fe0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d   the parameter m
36ff0 61 79 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20  ay change or.** 
37000 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61  be deallocated a
37010 66 74 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73  fter sqlite3_res
37020 75 6c 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75  ult_value() retu
37030 72 6e 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d  rns without harm
37040 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74  ..** ^A [protect
37050 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
37060 5d 20 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77  ] object may alw
37070 61 79 73 20 62 65 20 75 73 65 64 20 77 68 65 72  ays be used wher
37080 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65  e an.** [unprote
37090 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
370a0 75 65 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65  ue] object is re
370b0 71 75 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65  quired, so eithe
370c0 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71  r.** kind of [sq
370d0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
370e0 65 63 74 20 63 61 6e 20 62 65 20 75 73 65 64 20  ect can be used 
370f0 77 69 74 68 20 74 68 69 73 20 69 6e 74 65 72 66  with this interf
37100 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ace..**.** If th
37110 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
37120 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74   called from wit
37130 68 69 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e  hin the differen
37140 74 20 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e  t thread.** than
37150 20 74 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e   the one contain
37160 69 6e 67 20 74 68 65 20 61 70 70 6c 69 63 61 74  ing the applicat
37170 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
37180 74 69 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76  tion that receiv
37190 65 64 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74  ed.** the [sqlit
371a0 65 33 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e  e3_context] poin
371b0 74 65 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73  ter, the results
371c0 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
371d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  */.SQLITE_API vo
371e0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
371f0 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
37200 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
37210 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
37220 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49  *)(void*));.SQLI
37230 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
37240 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
37250 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
37260 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c  t*, double);.SQL
37270 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
37280 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
37290 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  r(sqlite3_contex
372a0 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  t*, const char*,
372b0 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
372c0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
372d0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71  esult_error16(sq
372e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
372f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
37300 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
37310 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37320 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73  t_error_toobig(s
37330 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
37340 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
37350 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
37360 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c  _error_nomem(sql
37370 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
37380 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37390 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
373a0 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65  rror_code(sqlite
373b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29  3_context*, int)
373c0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
373d0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
373e0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e  _int(sqlite3_con
373f0 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  text*, int);.SQL
37400 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
37410 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
37420 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  4(sqlite3_contex
37430 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  t*, sqlite3_int6
37440 34 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  4);.SQLITE_API v
37450 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37460 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
37470 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49 54  context*);.SQLIT
37480 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
37490 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
374a0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
374b0 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
374c0 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
374d0 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  ));.SQLITE_API v
374e0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
374f0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
37500 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
37510 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
37520 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
37530 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
37540 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37550 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63  xt16le(sqlite3_c
37560 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
37570 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
37580 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
37590 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
375a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
375b0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
375c0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
375d0 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
375e0 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50  id*));.SQLITE_AP
375f0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37600 65 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69  esult_value(sqli
37610 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71  te3_context*, sq
37620 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53  lite3_value*);.S
37630 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
37640 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65  qlite3_result_ze
37650 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  roblob(sqlite3_c
37660 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b  ontext*, int n);
37670 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
37680 3a 20 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c  : Define New Col
37690 6c 61 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73  lating Sequences
376a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
376b0 6e 63 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d  nctions add, rem
376c0 6f 76 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61  ove, or modify a
376d0 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73   [collation] ass
376e0 6f 63 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20  ociated.** with 
376f0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
37700 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
37710 69 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  ied as the first
37720 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
37730 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68   ^The name of th
37740 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61  e collation is a
37750 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a   UTF-8 string.**
37760 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65   for sqlite3_cre
37770 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20  ate_collation() 
37780 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61  and sqlite3_crea
37790 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
377a0 29 0a 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31  ).** and a UTF-1
377b0 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
377c0 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f  ve byte order fo
377d0 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  r sqlite3_create
377e0 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a  _collation16()..
377f0 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61  ** ^Collation na
37800 6d 65 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65  mes that compare
37810 20 65 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67   equal according
37820 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72   to [sqlite3_str
37830 6e 69 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20  nicmp()] are.** 
37840 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65  considered to be
37850 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a   the same name..
37860 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72  **.** ^(The thir
37870 64 20 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78  d argument (eTex
37880 74 52 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e  tRep) must be on
37890 65 20 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e  e of the constan
378a0 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  ts:.** <ul>.** <
378b0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38  li> [SQLITE_UTF8
378c0 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
378d0 54 45 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20  TE_UTF16LE],.** 
378e0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
378f0 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16BE],.** <li> [
37900 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f  SQLITE_UTF16], o
37910 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  r.** <li> [SQLIT
37920 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
37930 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20  ..** </ul>)^.** 
37940 5e 54 68 65 20 65 54 65 78 74 52 65 70 20 61 72  ^The eTextRep ar
37950 67 75 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65  gument determine
37960 73 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f  s the encoding o
37970 66 20 73 74 72 69 6e 67 73 20 70 61 73 73 65 64  f strings passed
37980 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  .** to the colla
37990 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ting function ca
379a0 6c 6c 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63  llback, xCallbac
379b0 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  k..** ^The [SQLI
379c0 54 45 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53  TE_UTF16] and [S
379d0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
379e0 4e 45 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20  NED] values for 
379f0 65 54 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63  eTextRep.** forc
37a00 65 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20  e strings to be 
37a10 55 54 46 31 36 20 77 69 74 68 20 6e 61 74 69 76  UTF16 with nativ
37a20 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a  e byte order..**
37a30 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
37a40 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c  F16_ALIGNED] val
37a50 75 65 20 66 6f 72 20 65 54 65 78 74 52 65 70 20  ue for eTextRep 
37a60 66 6f 72 63 65 73 20 73 74 72 69 6e 67 73 20 74  forces strings t
37a70 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e  o begin.** on an
37a80 20 65 76 65 6e 20 62 79 74 65 20 61 64 64 72 65   even byte addre
37a90 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ss..**.** ^The f
37aa0 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
37ab0 70 41 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c  pArg, is an appl
37ac0 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
37ad0 6e 74 65 72 20 74 68 61 74 20 69 73 20 70 61 73  nter that is pas
37ae0 73 65 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61  sed.** through a
37af0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
37b00 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c  ment to the coll
37b10 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
37b20 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  allback..**.** ^
37b30 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
37b40 6e 74 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69  nt, xCallback, i
37b50 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  s a pointer to t
37b60 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
37b70 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69  ction..** ^Multi
37b80 70 6c 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  ple collating fu
37b90 6e 63 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72  nctions can be r
37ba0 65 67 69 73 74 65 72 65 64 20 75 73 69 6e 67 20  egistered using 
37bb0 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75  the same name bu
37bc0 74 0a 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72  t.** with differ
37bd0 65 6e 74 20 65 54 65 78 74 52 65 70 20 70 61 72  ent eTextRep par
37be0 61 6d 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69  ameters and SQLi
37bf0 74 65 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63  te will use whic
37c00 68 65 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  hever.** functio
37c10 6e 20 72 65 71 75 69 72 65 73 20 74 68 65 20 6c  n requires the l
37c20 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64  east amount of d
37c30 61 74 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69  ata transformati
37c40 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78  on..** ^If the x
37c50 43 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e  Callback argumen
37c60 74 20 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74  t is NULL then t
37c70 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
37c80 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65  ction is.** dele
37c90 74 65 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20  ted.  ^When all 
37ca0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37cb0 6f 6e 73 20 68 61 76 69 6e 67 20 74 68 65 20 73  ons having the s
37cc0 61 6d 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c  ame name are del
37cd0 65 74 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f  eted,.** that co
37ce0 6c 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f  llation is no lo
37cf0 6e 67 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a  nger usable..**.
37d00 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e  ** ^The collatin
37d10 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62  g function callb
37d20 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  ack is invoked w
37d30 69 74 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ith a copy of th
37d40 65 20 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69  e pArg .** appli
37d50 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
37d60 74 65 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f  ter and with two
37d70 20 73 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20   strings in the 
37d80 65 6e 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69  encoding specifi
37d90 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65  ed.** by the eTe
37da0 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20  xtRep argument. 
37db0 20 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   The collating f
37dc0 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74  unction must ret
37dd0 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65  urn an.** intege
37de0 72 20 74 68 61 74 20 69 73 20 6e 65 67 61 74 69  r that is negati
37df0 76 65 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73  ve, zero, or pos
37e00 69 74 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20  itive.** if the 
37e10 66 69 72 73 74 20 73 74 72 69 6e 67 20 69 73 20  first string is 
37e20 6c 65 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c  less than, equal
37e30 20 74 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20   to, or greater 
37e40 74 68 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c  than the second,
37e50 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
37e60 2e 20 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66  .  A collating f
37e70 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77  unction must alw
37e80 61 79 73 20 72 65 74 75 72 6e 20 74 68 65 20 73  ays return the s
37e90 61 6d 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69  ame answer.** gi
37ea0 76 65 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70  ven the same inp
37eb0 75 74 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20  uts.  If two or 
37ec0 6d 6f 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66  more collating f
37ed0 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67  unctions are reg
37ee0 69 73 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68  istered.** to th
37ef0 65 20 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e  e same collation
37f00 20 6e 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66   name (using dif
37f10 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70 20  ferent eTextRep 
37f20 76 61 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c  values) then all
37f30 0a 2a 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e  .** must give an
37f40 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77   equivalent answ
37f50 65 72 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20  er when invoked 
37f60 77 69 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20  with equivalent 
37f70 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20  strings..** The 
37f80 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
37f90 6f 6e 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65  on must obey the
37fa0 20 66 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65   following prope
37fb0 72 74 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a  rties for all.**
37fc0 20 73 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61   strings A, B, a
37fd0 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e  nd C:.**.** <ol>
37fe0 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42  .** <li> If A==B
37ff0 20 74 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c   then B==A..** <
38000 6c 69 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20  li> If A==B and 
38010 42 3d 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a  B==C then A==C..
38020 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b  ** <li> If A&lt;
38030 42 20 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a  B THEN B&gt;A..*
38040 2a 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42  * <li> If A&lt;B
38050 20 61 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e   and B&lt;C then
38060 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c   A&lt;C..** </ol
38070 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c  >.**.** If a col
38080 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
38090 66 61 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65  fails any of the
380a0 20 61 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e   above constrain
380b0 74 73 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63  ts and that.** c
380c0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
380d0 6e 20 69 73 20 20 72 65 67 69 73 74 65 72 65 64  n is  registered
380e0 20 61 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20   and used, then 
380f0 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20  the behavior of 
38100 53 51 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64  SQLite.** is und
38110 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
38120 68 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  he sqlite3_creat
38130 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
38140 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
38150 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
38160 74 69 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74  tion().** with t
38170 68 65 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74  he addition that
38180 20 74 68 65 20 78 44 65 73 74 72 6f 79 20 63 61   the xDestroy ca
38190 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
381a0 64 20 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a  d on pArg when.*
381b0 2a 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  * the collating 
381c0 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65  function is dele
381d0 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69  ted..** ^Collati
381e0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
381f0 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68   deleted when th
38200 65 79 20 61 72 65 20 6f 76 65 72 72 69 64 64 65  ey are overridde
38210 6e 20 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61  n by later.** ca
38220 6c 6c 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61  lls to the colla
38230 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75  tion creation fu
38240 6e 63 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20  nctions or when 
38250 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  the.** [database
38260 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20   connection] is 
38270 63 6c 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71  closed using [sq
38280 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a  lite3_close()]..
38290 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74  **.** ^The xDest
382a0 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  roy callback is 
382b0 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65  <u>not</u> calle
382c0 64 20 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c  d if the .** sql
382d0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
382e0 61 74 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74  ation_v2() funct
382f0 69 6f 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c  ion fails.  Appl
38300 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e  ications that in
38310 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
38320 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
38330 5f 76 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e  _v2() with a non
38340 2d 4e 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61  -NULL xDestroy a
38350 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a  rgument should .
38360 2a 2a 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ** check the ret
38370 75 72 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73  urn code and dis
38380 70 6f 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c  pose of the appl
38390 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69  ication data poi
383a0 6e 74 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76  nter.** themselv
383b0 65 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 65  es rather than e
383c0 78 70 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20  xpecting SQLite 
383d0 74 6f 20 64 65 61 6c 20 77 69 74 68 20 69 74 20  to deal with it 
383e0 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69  for them..** Thi
383f0 73 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 66  s is different f
38400 72 6f 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20  rom every other 
38410 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
38420 2e 20 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74  .  The inconsist
38430 65 6e 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f  ency .** is unfo
38440 72 74 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e  rtunate but cann
38450 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20 77 69  ot be changed wi
38460 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62  thout breaking b
38470 61 63 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d  ackwards .** com
38480 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
38490 2a 20 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71  * See also:  [sq
384a0 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  lite3_collation_
384b0 6e 65 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73  needed()] and [s
384c0 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e  qlite3_collation
384d0 5f 6e 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f  _needed16()]..*/
384e0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
384f0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
38500 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
38510 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
38520 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
38530 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
38540 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
38550 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
38560 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
38570 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
38580 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  d*).);.SQLITE_AP
38590 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  I int sqlite3_cr
385a0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
385b0 32 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  2(.  sqlite3*, .
385c0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
385d0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
385e0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
385f0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
38600 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
38610 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
38620 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20  const void*),.  
38630 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28  void(*xDestroy)(
38640 76 6f 69 64 2a 29 0a 29 3b 0a 53 51 4c 49 54 45  void*).);.SQLITE
38650 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
38660 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
38670 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  n16(.  sqlite3*,
38680 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a   .  const void *
38690 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65  zName,.  int eTe
386a0 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a  xtRep, .  void *
386b0 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f  pArg,.  int(*xCo
386c0 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74  mpare)(void*,int
386d0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74  ,const void*,int
386e0 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b  ,const void*).);
386f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
38700 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64  : Collation Need
38710 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ed Callbacks.**.
38720 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20 68 61 76  ** ^To avoid hav
38730 69 6e 67 20 74 6f 20 72 65 67 69 73 74 65 72 20  ing to register 
38740 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  all collation se
38750 71 75 65 6e 63 65 73 20 62 65 66 6f 72 65 20 61  quences before a
38760 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e   database.** can
38770 20 62 65 20 75 73 65 64 2c 20 61 20 73 69 6e 67   be used, a sing
38780 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  le callback func
38790 74 69 6f 6e 20 6d 61 79 20 62 65 20 72 65 67 69  tion may be regi
387a0 73 74 65 72 65 64 20 77 69 74 68 20 74 68 65 0a  stered with the.
387b0 2a 2a 20 5b 64 61 74 61 62 6