System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 686d3488ec6f8183c9eadaaff1b351eff58786fe:


0000: 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /***************
0010: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0020: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0030: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0040: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a  ***************.
0050: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 69 73 20  ** This file is 
0060: 61 6e 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20  an amalgamation 
0070: 6f 66 20 6d 61 6e 79 20 73 65 70 61 72 61 74 65  of many separate
0080: 20 43 20 73 6f 75 72 63 65 20 66 69 6c 65 73 20   C source files 
0090: 66 72 6f 6d 20 53 51 4c 69 74 65 0a 2a 2a 20 76  from SQLite.** v
00a0: 65 72 73 69 6f 6e 20 33 2e 37 2e 31 34 2e 20 20  ersion 3.7.14.  
00b0: 42 79 20 63 6f 6d 62 69 6e 69 6e 67 20 61 6c 6c  By combining all
00c0: 20 74 68 65 20 69 6e 64 69 76 69 64 75 61 6c 20   the individual 
00d0: 43 20 63 6f 64 65 20 66 69 6c 65 73 20 69 6e 74  C code files int
00e0: 6f 20 74 68 69 73 20 0a 2a 2a 20 73 69 6e 67 6c  o this .** singl
00f0: 65 20 6c 61 72 67 65 20 66 69 6c 65 2c 20 74 68  e large file, th
0100: 65 20 65 6e 74 69 72 65 20 63 6f 64 65 20 63 61  e entire code ca
0110: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 61 73  n be compiled as
0120: 20 61 20 73 69 6e 67 6c 65 20 74 72 61 6e 73 6c   a single transl
0130: 61 74 69 6f 6e 0a 2a 2a 20 75 6e 69 74 2e 20 20  ation.** unit.  
0140: 54 68 69 73 20 61 6c 6c 6f 77 73 20 6d 61 6e 79  This allows many
0150: 20 63 6f 6d 70 69 6c 65 72 73 20 74 6f 20 64 6f   compilers to do
0160: 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 74   optimizations t
0170: 68 61 74 20 77 6f 75 6c 64 20 6e 6f 74 20 62 65  hat would not be
0180: 0a 2a 2a 20 70 6f 73 73 69 62 6c 65 20 69 66 20  .** possible if 
0190: 74 68 65 20 66 69 6c 65 73 20 77 65 72 65 20 63  the files were c
01a0: 6f 6d 70 69 6c 65 64 20 73 65 70 61 72 61 74 65  ompiled separate
01b0: 6c 79 2e 20 20 50 65 72 66 6f 72 6d 61 6e 63 65  ly.  Performance
01c0: 20 69 6d 70 72 6f 76 65 6d 65 6e 74 73 0a 2a 2a   improvements.**
01d0: 20 6f 66 20 35 25 20 6f 72 20 6d 6f 72 65 20 61   of 5% or more a
01e0: 72 65 20 63 6f 6d 6d 6f 6e 6c 79 20 73 65 65 6e  re commonly seen
01f0: 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
0200: 63 6f 6d 70 69 6c 65 64 20 61 73 20 61 20 73 69  compiled as a si
0210: 6e 67 6c 65 0a 2a 2a 20 74 72 61 6e 73 6c 61 74  ngle.** translat
0220: 69 6f 6e 20 75 6e 69 74 2e 0a 2a 2a 0a 2a 2a 20  ion unit..**.** 
0230: 54 68 69 73 20 66 69 6c 65 20 69 73 20 61 6c 6c  This file is all
0240: 20 79 6f 75 20 6e 65 65 64 20 74 6f 20 63 6f 6d   you need to com
0250: 70 69 6c 65 20 53 51 4c 69 74 65 2e 20 20 54 6f  pile SQLite.  To
0260: 20 75 73 65 20 53 51 4c 69 74 65 20 69 6e 20 6f   use SQLite in o
0270: 74 68 65 72 0a 2a 2a 20 70 72 6f 67 72 61 6d 73  ther.** programs
0280: 2c 20 79 6f 75 20 6e 65 65 64 20 74 68 69 73 20  , you need this 
0290: 66 69 6c 65 20 61 6e 64 20 74 68 65 20 22 73 71  file and the "sq
02a0: 6c 69 74 65 33 2e 68 22 20 68 65 61 64 65 72 20  lite3.h" header 
02b0: 66 69 6c 65 20 74 68 61 74 20 64 65 66 69 6e 65  file that define
02c0: 73 0a 2a 2a 20 74 68 65 20 70 72 6f 67 72 61 6d  s.** the program
02d0: 6d 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 74  ming interface t
02e0: 6f 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  o the SQLite lib
02f0: 72 61 72 79 2e 20 20 28 49 66 20 79 6f 75 20 64  rary.  (If you d
0300: 6f 20 6e 6f 74 20 68 61 76 65 20 0a 2a 2a 20 74  o not have .** t
0310: 68 65 20 22 73 71 6c 69 74 65 33 2e 68 22 20 68  he "sqlite3.h" h
0320: 65 61 64 65 72 20 66 69 6c 65 20 61 74 20 68 61  eader file at ha
0330: 6e 64 2c 20 79 6f 75 20 77 69 6c 6c 20 66 69 6e  nd, you will fin
0340: 64 20 61 20 63 6f 70 79 20 65 6d 62 65 64 64 65  d a copy embedde
0350: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
0360: 74 65 78 74 20 6f 66 20 74 68 69 73 20 66 69 6c  text of this fil
0370: 65 2e 20 20 53 65 61 72 63 68 20 66 6f 72 20 22  e.  Search for "
0380: 42 65 67 69 6e 20 66 69 6c 65 20 73 71 6c 69 74  Begin file sqlit
0390: 65 33 2e 68 22 20 74 6f 20 66 69 6e 64 20 74 68  e3.h" to find th
03a0: 65 20 73 74 61 72 74 0a 2a 2a 20 6f 66 20 74 68  e start.** of th
03b0: 65 20 65 6d 62 65 64 64 65 64 20 73 71 6c 69 74  e embedded sqlit
03c0: 65 33 2e 68 20 68 65 61 64 65 72 20 66 69 6c 65  e3.h header file
03d0: 2e 29 20 41 64 64 69 74 69 6f 6e 61 6c 20 63 6f  .) Additional co
03e0: 64 65 20 66 69 6c 65 73 20 6d 61 79 20 62 65 20  de files may be 
03f0: 6e 65 65 64 65 64 0a 2a 2a 20 69 66 20 79 6f 75  needed.** if you
0400: 20 77 61 6e 74 20 61 20 77 72 61 70 70 65 72 20   want a wrapper 
0410: 74 6f 20 69 6e 74 65 72 66 61 63 65 20 53 51 4c  to interface SQL
0420: 69 74 65 20 77 69 74 68 20 79 6f 75 72 20 63 68  ite with your ch
0430: 6f 69 63 65 20 6f 66 20 70 72 6f 67 72 61 6d 6d  oice of programm
0440: 69 6e 67 0a 2a 2a 20 6c 61 6e 67 75 61 67 65 2e  ing.** language.
0450: 20 54 68 65 20 63 6f 64 65 20 66 6f 72 20 74 68   The code for th
0460: 65 20 22 73 71 6c 69 74 65 33 22 20 63 6f 6d 6d  e "sqlite3" comm
0470: 61 6e 64 2d 6c 69 6e 65 20 73 68 65 6c 6c 20 69  and-line shell i
0480: 73 20 61 6c 73 6f 20 69 6e 20 61 0a 2a 2a 20 73  s also in a.** s
0490: 65 70 61 72 61 74 65 20 66 69 6c 65 2e 20 54 68  eparate file. Th
04a0: 69 73 20 66 69 6c 65 20 63 6f 6e 74 61 69 6e 73  is file contains
04b0: 20 6f 6e 6c 79 20 63 6f 64 65 20 66 6f 72 20 74   only code for t
04c0: 68 65 20 63 6f 72 65 20 53 51 4c 69 74 65 20 6c  he core SQLite l
04d0: 69 62 72 61 72 79 2e 0a 2a 2f 0a 23 64 65 66 69  ibrary..*/.#defi
04e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52 45 20 31  ne SQLITE_CORE 1
04f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
0500: 41 4d 41 4c 47 41 4d 41 54 49 4f 4e 20 31 0a 23  AMALGAMATION 1.#
0510: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 50 52  ifndef SQLITE_PR
0520: 49 56 41 54 45 0a 23 20 64 65 66 69 6e 65 20 53  IVATE.# define S
0530: 51 4c 49 54 45 5f 50 52 49 56 41 54 45 20 73 74  QLITE_PRIVATE st
0540: 61 74 69 63 0a 23 65 6e 64 69 66 0a 23 69 66 6e  atic.#endif.#ifn
0550: 64 65 66 20 53 51 4c 49 54 45 5f 41 50 49 0a 23  def SQLITE_API.#
0560: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41   define SQLITE_A
0570: 50 49 0a 23 65 6e 64 69 66 0a 2f 2a 2a 2a 2a 2a  PI.#endif./*****
0580: 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20  ********* Begin 
0590: 66 69 6c 65 20 73 71 6c 69 74 65 49 6e 74 2e 68  file sqliteInt.h
05a0: 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a   ***************
05b0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
05c0: 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20  ********/./*.** 
05d0: 32 30 30 31 20 53 65 70 74 65 6d 62 65 72 20 31  2001 September 1
05e0: 35 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  5.**.** The auth
05f0: 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70  or disclaims cop
0600: 79 72 69 67 68 74 20 74 6f 20 74 68 69 73 20 73  yright to this s
0610: 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20  ource code.  In 
0620: 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65  place of.** a le
0630: 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65  gal notice, here
0640: 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a   is a blessing:.
0650: 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  **.**    May you
0660: 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74   do good and not
0670: 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79   evil..**    May
0680: 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76   you find forgiv
0690: 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65  eness for yourse
06a0: 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f  lf and forgive o
06b0: 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79  thers..**    May
06c0: 20 79 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c   you share freel
06d0: 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20  y, never taking 
06e0: 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69  more than you gi
06f0: 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ve..**.*********
0700: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0710: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0720: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0730: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0740: 0a 2a 2a 20 49 6e 74 65 72 6e 61 6c 20 69 6e 74  .** Internal int
0750: 65 72 66 61 63 65 20 64 65 66 69 6e 69 74 69 6f  erface definitio
0760: 6e 73 20 66 6f 72 20 53 51 4c 69 74 65 2e 0a 2a  ns for SQLite..*
0770: 2a 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51  *.*/.#ifndef _SQ
0780: 4c 49 54 45 49 4e 54 5f 48 5f 0a 23 64 65 66 69  LITEINT_H_.#defi
0790: 6e 65 20 5f 53 51 4c 49 54 45 49 4e 54 5f 48 5f  ne _SQLITEINT_H_
07a0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 23 64  ../*.** These #d
07b0: 65 66 69 6e 65 73 20 73 68 6f 75 6c 64 20 65 6e  efines should en
07c0: 61 62 6c 65 20 3e 32 47 42 20 66 69 6c 65 20 73  able >2GB file s
07d0: 75 70 70 6f 72 74 20 6f 6e 20 50 4f 53 49 58 20  upport on POSIX 
07e0: 69 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  if the.** underl
07f0: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
0800: 79 73 74 65 6d 20 73 75 70 70 6f 72 74 73 20 69  ystem supports i
0810: 74 2e 20 20 49 66 20 74 68 65 20 4f 53 20 6c 61  t.  If the OS la
0820: 63 6b 73 0a 2a 2a 20 6c 61 72 67 65 20 66 69 6c  cks.** large fil
0830: 65 20 73 75 70 70 6f 72 74 2c 20 6f 72 20 69 66  e support, or if
0840: 20 74 68 65 20 4f 53 20 69 73 20 77 69 6e 64 6f   the OS is windo
0850: 77 73 2c 20 74 68 65 73 65 20 73 68 6f 75 6c 64  ws, these should
0860: 20 62 65 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 0a 2a   be no-ops..**.*
0870: 2a 20 54 69 63 6b 65 74 20 23 32 37 33 39 3a 20  * Ticket #2739: 
0880: 20 54 68 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f   The _LARGEFILE_
0890: 53 4f 55 52 43 45 20 6d 61 63 72 6f 20 6d 75 73  SOURCE macro mus
08a0: 74 20 61 70 70 65 61 72 20 62 65 66 6f 72 65 20  t appear before 
08b0: 61 6e 79 0a 2a 2a 20 73 79 73 74 65 6d 20 23 69  any.** system #i
08c0: 6e 63 6c 75 64 65 73 2e 20 20 48 65 6e 63 65 2c  ncludes.  Hence,
08d0: 20 74 68 69 73 20 62 6c 6f 63 6b 20 6f 66 20 63   this block of c
08e0: 6f 64 65 20 6d 75 73 74 20 62 65 20 74 68 65 20  ode must be the 
08f0: 76 65 72 79 20 66 69 72 73 74 0a 2a 2a 20 63 6f  very first.** co
0900: 64 65 20 69 6e 20 61 6c 6c 20 73 6f 75 72 63 65  de in all source
0910: 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 4c 61   files..**.** La
0920: 72 67 65 20 66 69 6c 65 20 73 75 70 70 6f 72 74  rge file support
0930: 20 63 61 6e 20 62 65 20 64 69 73 61 62 6c 65 64   can be disabled
0940: 20 75 73 69 6e 67 20 74 68 65 20 2d 44 53 51 4c   using the -DSQL
0950: 49 54 45 5f 44 49 53 41 42 4c 45 5f 4c 46 53 20  ITE_DISABLE_LFS 
0960: 73 77 69 74 63 68 0a 2a 2a 20 6f 6e 20 74 68 65  switch.** on the
0970: 20 63 6f 6d 70 69 6c 65 72 20 63 6f 6d 6d 61 6e   compiler comman
0980: 64 20 6c 69 6e 65 2e 20 20 54 68 69 73 20 69 73  d line.  This is
0990: 20 6e 65 63 65 73 73 61 72 79 20 69 66 20 79 6f   necessary if yo
09a0: 75 20 61 72 65 20 63 6f 6d 70 69 6c 69 6e 67 0a  u are compiling.
09b0: 2a 2a 20 6f 6e 20 61 20 72 65 63 65 6e 74 20 6d  ** on a recent m
09c0: 61 63 68 69 6e 65 20 28 65 78 3a 20 52 65 64 20  achine (ex: Red 
09d0: 48 61 74 20 37 2e 32 29 20 62 75 74 20 79 6f 75  Hat 7.2) but you
09e0: 20 77 61 6e 74 20 79 6f 75 72 20 63 6f 64 65 20   want your code 
09f0: 74 6f 20 77 6f 72 6b 0a 2a 2a 20 6f 6e 20 61 6e  to work.** on an
0a00: 20 6f 6c 64 65 72 20 6d 61 63 68 69 6e 65 20 28   older machine (
0a10: 65 78 3a 20 52 65 64 20 48 61 74 20 36 2e 30 29  ex: Red Hat 6.0)
0a20: 2e 20 20 49 66 20 79 6f 75 20 63 6f 6d 70 69 6c  .  If you compil
0a30: 65 20 6f 6e 20 52 65 64 20 48 61 74 20 37 2e 32  e on Red Hat 7.2
0a40: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 74 68 69 73  .** without this
0a50: 20 6f 70 74 69 6f 6e 2c 20 4c 46 53 20 69 73 20   option, LFS is 
0a60: 65 6e 61 62 6c 65 2e 20 20 42 75 74 20 4c 46 53  enable.  But LFS
0a70: 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74 20   does not exist 
0a80: 69 6e 20 74 68 65 20 6b 65 72 6e 65 6c 0a 2a 2a  in the kernel.**
0a90: 20 69 6e 20 52 65 64 20 48 61 74 20 36 2e 30 2c   in Red Hat 6.0,
0aa0: 20 73 6f 20 74 68 65 20 63 6f 64 65 20 77 6f 6e   so the code won
0ab0: 27 74 20 77 6f 72 6b 2e 20 20 48 65 6e 63 65 2c  't work.  Hence,
0ac0: 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 62 69 6e   for maximum bin
0ad0: 61 72 79 0a 2a 2a 20 70 6f 72 74 61 62 69 6c 69  ary.** portabili
0ae0: 74 79 20 79 6f 75 20 73 68 6f 75 6c 64 20 6f 6d  ty you should om
0af0: 69 74 20 4c 46 53 2e 0a 2a 2a 0a 2a 2a 20 53 69  it LFS..**.** Si
0b00: 6d 69 6c 61 72 20 69 73 20 74 72 75 65 20 66 6f  milar is true fo
0b10: 72 20 4d 61 63 20 4f 53 20 58 2e 20 20 4c 46 53  r Mac OS X.  LFS
0b20: 20 69 73 20 6f 6e 6c 79 20 73 75 70 70 6f 72 74   is only support
0b30: 65 64 20 6f 6e 20 4d 61 63 20 4f 53 20 58 20 39  ed on Mac OS X 9
0b40: 20 61 6e 64 20 6c 61 74 65 72 2e 0a 2a 2f 0a 23   and later..*/.#
0b50: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 49  ifndef SQLITE_DI
0b60: 53 41 42 4c 45 5f 4c 46 53 0a 23 20 64 65 66 69  SABLE_LFS.# defi
0b70: 6e 65 20 5f 4c 41 52 47 45 5f 46 49 4c 45 20 20  ne _LARGE_FILE  
0b80: 20 20 20 20 20 31 0a 23 20 69 66 6e 64 65 66 20       1.# ifndef 
0b90: 5f 46 49 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54  _FILE_OFFSET_BIT
0ba0: 53 0a 23 20 20 20 64 65 66 69 6e 65 20 5f 46 49  S.#   define _FI
0bb0: 4c 45 5f 4f 46 46 53 45 54 5f 42 49 54 53 20 36  LE_OFFSET_BITS 6
0bc0: 34 0a 23 20 65 6e 64 69 66 0a 23 20 64 65 66 69  4.# endif.# defi
0bd0: 6e 65 20 5f 4c 41 52 47 45 46 49 4c 45 5f 53 4f  ne _LARGEFILE_SO
0be0: 55 52 43 45 20 31 0a 23 65 6e 64 69 66 0a 0a 2f  URCE 1.#endif../
0bf0: 2a 0a 2a 2a 20 49 6e 63 6c 75 64 65 20 74 68 65  *.** Include the
0c00: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 68   configuration h
0c10: 65 61 64 65 72 20 6f 75 74 70 75 74 20 62 79 20  eader output by 
0c20: 27 63 6f 6e 66 69 67 75 72 65 27 20 69 66 20 77  'configure' if w
0c30: 65 27 72 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  e're using the.*
0c40: 2a 20 61 75 74 6f 63 6f 6e 66 2d 62 61 73 65 64  * autoconf-based
0c50: 20 62 75 69 6c 64 0a 2a 2f 0a 23 69 66 64 65 66   build.*/.#ifdef
0c60: 20 5f 48 41 56 45 5f 53 51 4c 49 54 45 5f 43 4f   _HAVE_SQLITE_CO
0c70: 4e 46 49 47 5f 48 0a 23 69 6e 63 6c 75 64 65 20  NFIG_H.#include 
0c80: 22 63 6f 6e 66 69 67 2e 68 22 0a 23 65 6e 64 69  "config.h".#endi
0c90: 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  f../************
0ca0: 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71 6c 69 74  ** Include sqlit
0cb0: 65 4c 69 6d 69 74 2e 68 20 69 6e 20 74 68 65 20  eLimit.h in the 
0cc0: 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65  middle of sqlite
0cd0: 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  Int.h **********
0ce0: 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  */./************
0cf0: 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65 20 73 71  ** Begin file sq
0d00: 6c 69 74 65 4c 69 6d 69 74 2e 68 20 2a 2a 2a 2a  liteLimit.h ****
0d10: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0d30: 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 37 20 4d 61  */./*.** 2007 Ma
0d40: 79 20 37 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  y 7.**.** The au
0d50: 74 68 6f 72 20 64 69 73 63 6c 61 69 6d 73 20 63  thor disclaims c
0d60: 6f 70 79 72 69 67 68 74 20 74 6f 20 74 68 69 73  opyright to this
0d70: 20 73 6f 75 72 63 65 20 63 6f 64 65 2e 20 20 49   source code.  I
0d80: 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 61 20  n place of.** a 
0d90: 6c 65 67 61 6c 20 6e 6f 74 69 63 65 2c 20 68 65  legal notice, he
0da0: 72 65 20 69 73 20 61 20 62 6c 65 73 73 69 6e 67  re is a blessing
0db0: 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d 61 79 20 79  :.**.**    May y
0dc0: 6f 75 20 64 6f 20 67 6f 6f 64 20 61 6e 64 20 6e  ou do good and n
0dd0: 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d  ot evil..**    M
0de0: 61 79 20 79 6f 75 20 66 69 6e 64 20 66 6f 72 67  ay you find forg
0df0: 69 76 65 6e 65 73 73 20 66 6f 72 20 79 6f 75 72  iveness for your
0e00: 73 65 6c 66 20 61 6e 64 20 66 6f 72 67 69 76 65  self and forgive
0e10: 20 6f 74 68 65 72 73 2e 0a 2a 2a 20 20 20 20 4d   others..**    M
0e20: 61 79 20 79 6f 75 20 73 68 61 72 65 20 66 72 65  ay you share fre
0e30: 65 6c 79 2c 20 6e 65 76 65 72 20 74 61 6b 69 6e  ely, never takin
0e40: 67 20 6d 6f 72 65 20 74 68 61 6e 20 79 6f 75 20  g more than you 
0e50: 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a  give..**.*******
0e60: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0ea0: 2a 2a 0a 2a 2a 20 0a 2a 2a 20 54 68 69 73 20 66  **.** .** This f
0eb0: 69 6c 65 20 64 65 66 69 6e 65 73 20 76 61 72 69  ile defines vari
0ec0: 6f 75 73 20 6c 69 6d 69 74 73 20 6f 66 20 77 68  ous limits of wh
0ed0: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 70 72  at SQLite can pr
0ee0: 6f 63 65 73 73 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a  ocess..*/../*.**
0ef0: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   The maximum len
0f00: 67 74 68 20 6f 66 20 61 20 54 45 58 54 20 6f 72  gth of a TEXT or
0f10: 20 42 4c 4f 42 20 69 6e 20 62 79 74 65 73 2e 20   BLOB in bytes. 
0f20: 20 20 54 68 69 73 20 61 6c 73 6f 0a 2a 2a 20 6c    This also.** l
0f30: 69 6d 69 74 73 20 74 68 65 20 73 69 7a 65 20 6f  imits the size o
0f40: 66 20 61 20 72 6f 77 20 69 6e 20 61 20 74 61 62  f a row in a tab
0f50: 6c 65 20 6f 72 20 69 6e 64 65 78 2e 0a 2a 2a 0a  le or index..**.
0f60: 2a 2a 20 54 68 65 20 68 61 72 64 20 6c 69 6d 69  ** The hard limi
0f70: 74 20 69 73 20 74 68 65 20 61 62 69 6c 69 74 79  t is the ability
0f80: 20 6f 66 20 61 20 33 32 2d 62 69 74 20 73 69 67   of a 32-bit sig
0f90: 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 74  ned integer.** t
0fa0: 6f 20 63 6f 75 6e 74 20 74 68 65 20 73 69 7a 65  o count the size
0fb0: 3a 20 32 5e 33 31 2d 31 20 6f 72 20 32 31 34 37  : 2^31-1 or 2147
0fc0: 34 38 33 36 34 37 2e 0a 2a 2f 0a 23 69 66 6e 64  483647..*/.#ifnd
0fd0: 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 45  ef SQLITE_MAX_LE
0fe0: 4e 47 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51  NGTH.# define SQ
0ff0: 4c 49 54 45 5f 4d 41 58 5f 4c 45 4e 47 54 48 20  LITE_MAX_LENGTH 
1000: 31 30 30 30 30 30 30 30 30 30 0a 23 65 6e 64 69  1000000000.#endi
1010: 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 69 73  f../*.** This is
1020: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
1030: 62 65 72 20 6f 66 0a 2a 2a 0a 2a 2a 20 20 20 20  ber of.**.**    
1040: 2a 20 43 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  * Columns in a t
1050: 61 62 6c 65 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c  able.**    * Col
1060: 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78  umns in an index
1070: 0a 2a 2a 20 20 20 20 2a 20 43 6f 6c 75 6d 6e 73  .**    * Columns
1080: 20 69 6e 20 61 20 76 69 65 77 0a 2a 2a 20 20 20   in a view.**   
1090: 20 2a 20 54 65 72 6d 73 20 69 6e 20 74 68 65 20   * Terms in the 
10a0: 53 45 54 20 63 6c 61 75 73 65 20 6f 66 20 61 6e  SET clause of an
10b0: 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
10c0: 74 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20  t.**    * Terms 
10d0: 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  in the result se
10e0: 74 20 6f 66 20 61 20 53 45 4c 45 43 54 20 73 74  t of a SELECT st
10f0: 61 74 65 6d 65 6e 74 0a 2a 2a 20 20 20 20 2a 20  atement.**    * 
1100: 54 65 72 6d 73 20 69 6e 20 74 68 65 20 47 52 4f  Terms in the GRO
1110: 55 50 20 42 59 20 6f 72 20 4f 52 44 45 52 20 42  UP BY or ORDER B
1120: 59 20 63 6c 61 75 73 65 73 20 6f 66 20 61 20 53  Y clauses of a S
1130: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1140: 0a 2a 2a 20 20 20 20 2a 20 54 65 72 6d 73 20 69  .**    * Terms i
1150: 6e 20 74 68 65 20 56 41 4c 55 45 53 20 63 6c 61  n the VALUES cla
1160: 75 73 65 20 6f 66 20 61 6e 20 49 4e 53 45 52 54  use of an INSERT
1170: 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a   statement.**.**
1180: 20 54 68 65 20 68 61 72 64 20 75 70 70 65 72 20   The hard upper 
1190: 6c 69 6d 69 74 20 68 65 72 65 20 69 73 20 33 32  limit here is 32
11a0: 36 37 36 2e 20 20 4d 6f 73 74 20 64 61 74 61 62  676.  Most datab
11b0: 61 73 65 20 70 65 6f 70 6c 65 20 77 69 6c 6c 0a  ase people will.
11c0: 2a 2a 20 74 65 6c 6c 20 79 6f 75 20 74 68 61 74  ** tell you that
11d0: 20 69 6e 20 61 20 77 65 6c 6c 2d 6e 6f 72 6d 61   in a well-norma
11e0: 6c 69 7a 65 64 20 64 61 74 61 62 61 73 65 2c 20  lized database, 
11f0: 79 6f 75 20 75 73 75 61 6c 6c 79 20 73 68 6f 75  you usually shou
1200: 6c 64 0a 2a 2a 20 6e 6f 74 20 68 61 76 65 20 6d  ld.** not have m
1210: 6f 72 65 20 74 68 61 6e 20 61 20 64 6f 7a 65 6e  ore than a dozen
1220: 20 6f 72 20 73 6f 20 63 6f 6c 75 6d 6e 73 20 69   or so columns i
1230: 6e 20 61 6e 79 20 74 61 62 6c 65 2e 20 20 41 6e  n any table.  An
1240: 64 20 69 66 0a 2a 2a 20 74 68 61 74 20 69 73 20  d if.** that is 
1250: 74 68 65 20 63 61 73 65 2c 20 74 68 65 72 65 20  the case, there 
1260: 69 73 20 6e 6f 20 70 6f 69 6e 74 20 69 6e 20 68  is no point in h
1270: 61 76 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aving more than 
1280: 61 20 66 65 77 0a 2a 2a 20 64 6f 7a 65 6e 20 76  a few.** dozen v
1290: 61 6c 75 65 73 20 69 6e 20 61 6e 79 20 6f 66 20  alues in any of 
12a0: 74 68 65 20 6f 74 68 65 72 20 73 69 74 75 61 74  the other situat
12b0: 69 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61  ions described a
12c0: 62 6f 76 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  bove..*/.#ifndef
12d0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 43 4f 4c 55   SQLITE_MAX_COLU
12e0: 4d 4e 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  MN.# define SQLI
12f0: 54 45 5f 4d 41 58 5f 43 4f 4c 55 4d 4e 20 32 30  TE_MAX_COLUMN 20
1300: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1310: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   The maximum len
1320: 67 74 68 20 6f 66 20 61 20 73 69 6e 67 6c 65 20  gth of a single 
1330: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  SQL statement in
1340: 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20 49 74   bytes..**.** It
1350: 20 75 73 65 64 20 74 6f 20 62 65 20 74 68 65 20   used to be the 
1360: 63 61 73 65 20 74 68 61 74 20 73 65 74 74 69 6e  case that settin
1370: 67 20 74 68 69 73 20 76 61 6c 75 65 20 74 6f 20  g this value to 
1380: 7a 65 72 6f 20 77 6f 75 6c 64 0a 2a 2a 20 74 75  zero would.** tu
1390: 72 6e 20 74 68 65 20 6c 69 6d 69 74 20 6f 66 66  rn the limit off
13a0: 2e 20 20 54 68 61 74 20 69 73 20 6e 6f 20 6c 6f  .  That is no lo
13b0: 6e 67 65 72 20 74 72 75 65 2e 20 20 49 74 20 69  nger true.  It i
13c0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 0a 2a  s not possible.*
13d0: 2a 20 74 6f 20 74 75 72 6e 20 74 68 69 73 20 6c  * to turn this l
13e0: 69 6d 69 74 20 6f 66 66 2e 0a 2a 2f 0a 23 69 66  imit off..*/.#if
13f0: 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58 5f  ndef SQLITE_MAX_
1400: 53 51 4c 5f 4c 45 4e 47 54 48 0a 23 20 64 65 66  SQL_LENGTH.# def
1410: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53  ine SQLITE_MAX_S
1420: 51 4c 5f 4c 45 4e 47 54 48 20 31 30 30 30 30 30  QL_LENGTH 100000
1430: 30 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  0000.#endif../*.
1440: 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 64  ** The maximum d
1450: 65 70 74 68 20 6f 66 20 61 6e 20 65 78 70 72 65  epth of an expre
1460: 73 73 69 6f 6e 20 74 72 65 65 2e 20 54 68 69 73  ssion tree. This
1470: 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 0a   is limited to .
1480: 2a 2a 20 73 6f 6d 65 20 65 78 74 65 6e 74 20 62  ** some extent b
1490: 79 20 53 51 4c 49 54 45 5f 4d 41 58 5f 53 51 4c  y SQLITE_MAX_SQL
14a0: 5f 4c 45 4e 47 54 48 2e 20 42 75 74 20 73 6f 6d  _LENGTH. But som
14b0: 65 74 69 6d 65 20 79 6f 75 20 6d 69 67 68 74 20  etime you might 
14c0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 70 6c 61 63  .** want to plac
14d0: 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20 6c 69  e more severe li
14e0: 6d 69 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70  mits on the comp
14f0: 6c 65 78 69 74 79 20 6f 66 20 61 6e 20 0a 2a 2a  lexity of an .**
1500: 20 65 78 70 72 65 73 73 69 6f 6e 2e 0a 2a 2a 0a   expression..**.
1510: 2a 2a 20 41 20 76 61 6c 75 65 20 6f 66 20 30 20  ** A value of 0 
1520: 75 73 65 64 20 74 6f 20 6d 65 61 6e 20 74 68 61  used to mean tha
1530: 74 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20  t the limit was 
1540: 6e 6f 74 20 65 6e 66 6f 72 63 65 64 2e 0a 2a 2a  not enforced..**
1550: 20 42 75 74 20 74 68 61 74 20 69 73 20 6e 6f 20   But that is no 
1560: 6c 6f 6e 67 65 72 20 74 72 75 65 2e 20 20 54 68  longer true.  Th
1570: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 77 20 73  e limit is now s
1580: 74 72 69 63 74 6c 79 20 65 6e 66 6f 72 63 65 64  trictly enforced
1590: 0a 2a 2a 20 61 74 20 61 6c 6c 20 74 69 6d 65 73  .** at all times
15a0: 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  ..*/.#ifndef SQL
15b0: 49 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50  ITE_MAX_EXPR_DEP
15c0: 54 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  TH.# define SQLI
15d0: 54 45 5f 4d 41 58 5f 45 58 50 52 5f 44 45 50 54  TE_MAX_EXPR_DEPT
15e0: 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f  H 1000.#endif../
15f0: 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d  *.** The maximum
1600: 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73   number of terms
1610: 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53   in a compound S
1620: 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e  ELECT statement.
1630: 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 67 65 6e  .** The code gen
1640: 65 72 61 74 6f 72 20 66 6f 72 20 63 6f 6d 70 6f  erator for compo
1650: 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
1660: 6d 65 6e 74 73 20 64 6f 65 73 20 6f 6e 65 0a 2a  ments does one.*
1670: 2a 20 6c 65 76 65 6c 20 6f 66 20 72 65 63 75 72  * level of recur
1680: 73 69 6f 6e 20 66 6f 72 20 65 61 63 68 20 74 65  sion for each te
1690: 72 6d 2e 20 20 41 20 73 74 61 63 6b 20 6f 76 65  rm.  A stack ove
16a0: 72 66 6c 6f 77 20 63 61 6e 20 72 65 73 75 6c 74  rflow can result
16b0: 0a 2a 2a 20 69 66 20 74 68 65 20 6e 75 6d 62 65  .** if the numbe
16c0: 72 20 6f 66 20 74 65 72 6d 73 20 69 73 20 74 6f  r of terms is to
16d0: 6f 20 6c 61 72 67 65 2e 20 20 49 6e 20 70 72 61  o large.  In pra
16e0: 63 74 69 63 65 2c 20 6d 6f 73 74 20 53 51 4c 0a  ctice, most SQL.
16f0: 2a 2a 20 6e 65 76 65 72 20 68 61 73 20 6d 6f 72  ** never has mor
1700: 65 20 74 68 61 6e 20 33 20 6f 72 20 34 20 74 65  e than 3 or 4 te
1710: 72 6d 73 2e 20 20 55 73 65 20 61 20 76 61 6c 75  rms.  Use a valu
1720: 65 20 6f 66 20 30 20 74 6f 20 64 69 73 61 62 6c  e of 0 to disabl
1730: 65 0a 2a 2a 20 61 6e 79 20 6c 69 6d 69 74 20 6f  e.** any limit o
1740: 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  n the number of 
1750: 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
1760: 75 6e 74 20 53 45 4c 45 43 54 2e 0a 2a 2f 0a 23  unt SELECT..*/.#
1770: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41  ifndef SQLITE_MA
1780: 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  X_COMPOUND_SELEC
1790: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  T.# define SQLIT
17a0: 45 5f 4d 41 58 5f 43 4f 4d 50 4f 55 4e 44 5f 53  E_MAX_COMPOUND_S
17b0: 45 4c 45 43 54 20 35 30 30 0a 23 65 6e 64 69 66  ELECT 500.#endif
17c0: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78 69  ../*.** The maxi
17d0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 6f 70  mum number of op
17e0: 63 6f 64 65 73 20 69 6e 20 61 20 56 44 42 45 20  codes in a VDBE 
17f0: 70 72 6f 67 72 61 6d 2e 0a 2a 2a 20 4e 6f 74 20  program..** Not 
1800: 63 75 72 72 65 6e 74 6c 79 20 65 6e 66 6f 72 63  currently enforc
1810: 65 64 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53  ed..*/.#ifndef S
1820: 51 4c 49 54 45 5f 4d 41 58 5f 56 44 42 45 5f 4f  QLITE_MAX_VDBE_O
1830: 50 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  P.# define SQLIT
1840: 45 5f 4d 41 58 5f 56 44 42 45 5f 4f 50 20 32 35  E_MAX_VDBE_OP 25
1850: 30 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  000.#endif../*.*
1860: 2a 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  * The maximum nu
1870: 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
1880: 73 20 74 6f 20 61 6e 20 53 51 4c 20 66 75 6e 63  s to an SQL func
1890: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  tion..*/.#ifndef
18a0: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e 43   SQLITE_MAX_FUNC
18b0: 54 49 4f 4e 5f 41 52 47 0a 23 20 64 65 66 69 6e  TION_ARG.# defin
18c0: 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 46 55 4e  e SQLITE_MAX_FUN
18d0: 43 54 49 4f 4e 5f 41 52 47 20 31 32 37 0a 23 65  CTION_ARG 127.#e
18e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  ndif../*.** The 
18f0: 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
1900: 66 20 69 6e 2d 6d 65 6d 6f 72 79 20 70 61 67 65  f in-memory page
1910: 73 20 74 6f 20 75 73 65 20 66 6f 72 20 74 68 65  s to use for the
1920: 20 6d 61 69 6e 20 64 61 74 61 62 61 73 65 0a 2a   main database.*
1930: 2a 20 74 61 62 6c 65 20 61 6e 64 20 66 6f 72 20  * table and for 
1940: 74 65 6d 70 6f 72 61 72 79 20 74 61 62 6c 65 73  temporary tables
1950: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45  .  The SQLITE_DE
1960: 46 41 55 4c 54 5f 43 41 43 48 45 5f 53 49 5a 45  FAULT_CACHE_SIZE
1970: 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
1980: 54 45 5f 44 45 46 41 55 4c 54 5f 43 41 43 48 45  TE_DEFAULT_CACHE
1990: 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53  _SIZE.# define S
19a0: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 43 41  QLITE_DEFAULT_CA
19b0: 43 48 45 5f 53 49 5a 45 20 20 32 30 30 30 0a 23  CHE_SIZE  2000.#
19c0: 65 6e 64 69 66 0a 23 69 66 6e 64 65 66 20 53 51  endif.#ifndef SQ
19d0: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 54 45 4d  LITE_DEFAULT_TEM
19e0: 50 5f 43 41 43 48 45 5f 53 49 5a 45 0a 23 20 64  P_CACHE_SIZE.# d
19f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
1a00: 41 55 4c 54 5f 54 45 4d 50 5f 43 41 43 48 45 5f  AULT_TEMP_CACHE_
1a10: 53 49 5a 45 20 20 35 30 30 0a 23 65 6e 64 69 66  SIZE  500.#endif
1a20: 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 64 65 66 61  ../*.** The defa
1a30: 75 6c 74 20 6e 75 6d 62 65 72 20 6f 66 20 66 72  ult number of fr
1a40: 61 6d 65 73 20 74 6f 20 61 63 63 75 6d 75 6c 61  ames to accumula
1a50: 74 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69  te in the log fi
1a60: 6c 65 20 62 65 66 6f 72 65 0a 2a 2a 20 63 68 65  le before.** che
1a70: 63 6b 70 6f 69 6e 74 69 6e 67 20 74 68 65 20 64  ckpointing the d
1a80: 61 74 61 62 61 73 65 20 69 6e 20 57 41 4c 20 6d  atabase in WAL m
1a90: 6f 64 65 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ode..*/.#ifndef 
1aa0: 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 57  SQLITE_DEFAULT_W
1ab0: 41 4c 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e  AL_AUTOCHECKPOIN
1ac0: 54 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  T.# define SQLIT
1ad0: 45 5f 44 45 46 41 55 4c 54 5f 57 41 4c 5f 41 55  E_DEFAULT_WAL_AU
1ae0: 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 20 31 30  TOCHECKPOINT  10
1af0: 30 30 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  00.#endif../*.**
1b00: 20 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   The maximum num
1b10: 62 65 72 20 6f 66 20 61 74 74 61 63 68 65 64 20  ber of attached 
1b20: 64 61 74 61 62 61 73 65 73 2e 20 20 54 68 69 73  databases.  This
1b30: 20 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e   must be between
1b40: 20 30 0a 2a 2a 20 61 6e 64 20 36 32 2e 20 20 54   0.** and 62.  T
1b50: 68 65 20 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  he upper bound o
1b60: 6e 20 36 32 20 69 73 20 62 65 63 61 75 73 65 20  n 62 is because 
1b70: 61 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  a 64-bit integer
1b80: 20 62 69 74 6d 61 70 0a 2a 2a 20 69 73 20 75 73   bitmap.** is us
1b90: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
1ba0: 20 74 72 61 63 6b 20 61 74 74 61 63 68 65 64 20   track attached 
1bb0: 64 61 74 61 62 61 73 65 73 2e 0a 2a 2f 0a 23 69  databases..*/.#i
1bc0: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1bd0: 5f 41 54 54 41 43 48 45 44 0a 23 20 64 65 66 69  _ATTACHED.# defi
1be0: 6e 65 20 53 51 4c 49 54 45 5f 4d 41 58 5f 41 54  ne SQLITE_MAX_AT
1bf0: 54 41 43 48 45 44 20 31 30 0a 23 65 6e 64 69 66  TACHED 10.#endif
1c00: 0a 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61 78  .../*.** The max
1c10: 69 6d 75 6d 20 76 61 6c 75 65 20 6f 66 20 61 20  imum value of a 
1c20: 3f 6e 6e 6e 20 77 69 6c 64 63 61 72 64 20 74 68  ?nnn wildcard th
1c30: 61 74 20 74 68 65 20 70 61 72 73 65 72 20 77 69  at the parser wi
1c40: 6c 6c 20 61 63 63 65 70 74 2e 0a 2a 2f 0a 23 69  ll accept..*/.#i
1c50: 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d 41 58  fndef SQLITE_MAX
1c60: 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
1c70: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
1c80: 5f 4d 41 58 5f 56 41 52 49 41 42 4c 45 5f 4e 55  _MAX_VARIABLE_NU
1c90: 4d 42 45 52 20 39 39 39 0a 23 65 6e 64 69 66 0a  MBER 999.#endif.
1ca0: 0a 2f 2a 20 4d 61 78 69 6d 75 6d 20 70 61 67 65  ./* Maximum page
1cb0: 20 73 69 7a 65 2e 20 20 54 68 65 20 75 70 70 65   size.  The uppe
1cc0: 72 20 62 6f 75 6e 64 20 6f 6e 20 74 68 69 73 20  r bound on this 
1cd0: 76 61 6c 75 65 20 69 73 20 36 35 35 33 36 2e 20  value is 65536. 
1ce0: 20 54 68 69 73 20 61 20 6c 69 6d 69 74 0a 2a 2a   This a limit.**
1cf0: 20 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65 20   imposed by the 
1d00: 75 73 65 20 6f 66 20 31 36 2d 62 69 74 20 6f 66  use of 16-bit of
1d10: 66 73 65 74 73 20 77 69 74 68 69 6e 20 65 61 63  fsets within eac
1d20: 68 20 70 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 45 61  h page..**.** Ea
1d30: 72 6c 69 65 72 20 76 65 72 73 69 6f 6e 73 20 6f  rlier versions o
1d40: 66 20 53 51 4c 69 74 65 20 61 6c 6c 6f 77 65 64  f SQLite allowed
1d50: 20 74 68 65 20 75 73 65 72 20 74 6f 20 63 68 61   the user to cha
1d60: 6e 67 65 20 74 68 69 73 20 76 61 6c 75 65 20 61  nge this value a
1d70: 74 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t.** compile tim
1d80: 65 2e 20 54 68 69 73 20 69 73 20 6e 6f 20 6c 6f  e. This is no lo
1d90: 6e 67 65 72 20 70 65 72 6d 69 74 74 65 64 2c 20  nger permitted, 
1da0: 6f 6e 20 74 68 65 20 67 72 6f 75 6e 64 73 20 74  on the grounds t
1db0: 68 61 74 20 69 74 20 63 72 65 61 74 65 73 0a 2a  hat it creates.*
1dc0: 2a 20 61 20 6c 69 62 72 61 72 79 20 74 68 61 74  * a library that
1dd0: 20 69 73 20 74 65 63 68 6e 69 63 61 6c 6c 79 20   is technically 
1de0: 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 69 74  incompatible wit
1df0: 68 20 61 6e 20 53 51 4c 69 74 65 20 6c 69 62 72  h an SQLite libr
1e00: 61 72 79 20 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  ary .** compiled
1e10: 20 77 69 74 68 20 61 20 64 69 66 66 65 72 65 6e   with a differen
1e20: 74 20 6c 69 6d 69 74 2e 20 49 66 20 61 20 70 72  t limit. If a pr
1e30: 6f 63 65 73 73 20 6f 70 65 72 61 74 69 6e 67 20  ocess operating 
1e40: 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 0a 2a  on a database .*
1e50: 2a 20 77 69 74 68 20 61 20 70 61 67 65 2d 73 69  * with a page-si
1e60: 7a 65 20 6f 66 20 36 35 35 33 36 20 62 79 74 65  ze of 65536 byte
1e70: 73 20 63 72 61 73 68 65 73 2c 20 74 68 65 6e 20  s crashes, then 
1e80: 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 53  an instance of S
1e90: 51 4c 69 74 65 20 0a 2a 2a 20 63 6f 6d 70 69 6c  QLite .** compil
1ea0: 65 64 20 77 69 74 68 20 74 68 65 20 64 65 66 61  ed with the defa
1eb0: 75 6c 74 20 70 61 67 65 2d 73 69 7a 65 20 6c 69  ult page-size li
1ec0: 6d 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20  mit will not be 
1ed0: 61 62 6c 65 20 74 6f 20 72 6f 6c 6c 62 61 63 6b  able to rollback
1ee0: 20 0a 2a 2a 20 74 68 65 20 61 62 6f 72 74 65 64   .** the aborted
1ef0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54 68   transaction. Th
1f00: 69 73 20 63 6f 75 6c 64 20 6c 65 61 64 20 74 6f  is could lead to
1f10: 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   database corrup
1f20: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  tion..*/.#ifdef 
1f30: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
1f40: 53 49 5a 45 0a 23 20 75 6e 64 65 66 20 53 51 4c  SIZE.# undef SQL
1f50: 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a  ITE_MAX_PAGE_SIZ
1f60: 45 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65  E.#endif.#define
1f70: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45   SQLITE_MAX_PAGE
1f80: 5f 53 49 5a 45 20 36 35 35 33 36 0a 0a 0a 2f 2a  _SIZE 65536.../*
1f90: 0a 2a 2a 20 54 68 65 20 64 65 66 61 75 6c 74 20  .** The default 
1fa0: 73 69 7a 65 20 6f 66 20 61 20 64 61 74 61 62 61  size of a databa
1fb0: 73 65 20 70 61 67 65 2e 0a 2a 2f 0a 23 69 66 6e  se page..*/.#ifn
1fc0: 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41 55  def SQLITE_DEFAU
1fd0: 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 64  LT_PAGE_SIZE.# d
1fe0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 46  efine SQLITE_DEF
1ff0: 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 31  AULT_PAGE_SIZE 1
2000: 30 32 34 0a 23 65 6e 64 69 66 0a 23 69 66 20 53  024.#endif.#if S
2010: 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41  QLITE_DEFAULT_PA
2020: 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54 45 5f 4d  GE_SIZE>SQLITE_M
2030: 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20 75  AX_PAGE_SIZE.# u
2040: 6e 64 65 66 20 53 51 4c 49 54 45 5f 44 45 46 41  ndef SQLITE_DEFA
2050: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 0a 23 20  ULT_PAGE_SIZE.# 
2060: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
2070: 46 41 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20  FAULT_PAGE_SIZE 
2080: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
2090: 53 49 5a 45 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  SIZE.#endif../*.
20a0: 2a 2a 20 4f 72 64 69 6e 61 72 69 6c 79 2c 20 69  ** Ordinarily, i
20b0: 66 20 6e 6f 20 76 61 6c 75 65 20 69 73 20 65 78  f no value is ex
20c0: 70 6c 69 63 69 74 6c 79 20 70 72 6f 76 69 64 65  plicitly provide
20d0: 64 2c 20 53 51 4c 69 74 65 20 63 72 65 61 74 65  d, SQLite create
20e0: 73 20 64 61 74 61 62 61 73 65 73 0a 2a 2a 20 77  s databases.** w
20f0: 69 74 68 20 70 61 67 65 20 73 69 7a 65 20 53 51  ith page size SQ
2100: 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 50 41 47  LITE_DEFAULT_PAG
2110: 45 5f 53 49 5a 45 2e 20 48 6f 77 65 76 65 72 2c  E_SIZE. However,
2120: 20 62 61 73 65 64 20 6f 6e 20 63 65 72 74 61 69   based on certai
2130: 6e 0a 2a 2a 20 64 65 76 69 63 65 20 63 68 61 72  n.** device char
2140: 61 63 74 65 72 69 73 74 69 63 73 20 28 73 65 63  acteristics (sec
2150: 74 6f 72 2d 73 69 7a 65 20 61 6e 64 20 61 74 6f  tor-size and ato
2160: 6d 69 63 20 77 72 69 74 65 28 29 20 73 75 70 70  mic write() supp
2170: 6f 72 74 29 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  ort),.** SQLite 
2180: 6d 61 79 20 63 68 6f 6f 73 65 20 61 20 6c 61 72  may choose a lar
2190: 67 65 72 20 76 61 6c 75 65 2e 20 54 68 69 73 20  ger value. This 
21a0: 63 6f 6e 73 74 61 6e 74 20 69 73 20 74 68 65 20  constant is the 
21b0: 6d 61 78 69 6d 75 6d 20 76 61 6c 75 65 0a 2a 2a  maximum value.**
21c0: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 63 68 6f   SQLite will cho
21d0: 6f 73 65 20 6f 6e 20 69 74 73 20 6f 77 6e 2e 0a  ose on its own..
21e0: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
21f0: 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54 5f 50 41  E_MAX_DEFAULT_PA
2200: 47 45 5f 53 49 5a 45 0a 23 20 64 65 66 69 6e 65  GE_SIZE.# define
2210: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41   SQLITE_MAX_DEFA
2220: 55 4c 54 5f 50 41 47 45 5f 53 49 5a 45 20 38 31  ULT_PAGE_SIZE 81
2230: 39 32 0a 23 65 6e 64 69 66 0a 23 69 66 20 53 51  92.#endif.#if SQ
2240: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54  LITE_MAX_DEFAULT
2250: 5f 50 41 47 45 5f 53 49 5a 45 3e 53 51 4c 49 54  _PAGE_SIZE>SQLIT
2260: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a  E_MAX_PAGE_SIZE.
2270: 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 4d  # undef SQLITE_M
2280: 41 58 5f 44 45 46 41 55 4c 54 5f 50 41 47 45 5f  AX_DEFAULT_PAGE_
2290: 53 49 5a 45 0a 23 20 64 65 66 69 6e 65 20 53 51  SIZE.# define SQ
22a0: 4c 49 54 45 5f 4d 41 58 5f 44 45 46 41 55 4c 54  LITE_MAX_DEFAULT
22b0: 5f 50 41 47 45 5f 53 49 5a 45 20 53 51 4c 49 54  _PAGE_SIZE SQLIT
22c0: 45 5f 4d 41 58 5f 50 41 47 45 5f 53 49 5a 45 0a  E_MAX_PAGE_SIZE.
22d0: 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 4d  #endif.../*.** M
22e0: 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
22f0: 20 70 61 67 65 73 20 69 6e 20 6f 6e 65 20 64 61   pages in one da
2300: 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a  tabase file..**.
2310: 2a 2a 20 54 68 69 73 20 69 73 20 72 65 61 6c 6c  ** This is reall
2320: 79 20 6a 75 73 74 20 74 68 65 20 64 65 66 61 75  y just the defau
2330: 6c 74 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  lt value for the
2340: 20 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20   max_page_count 
2350: 70 72 61 67 6d 61 2e 0a 2a 2a 20 54 68 69 73 20  pragma..** This 
2360: 76 61 6c 75 65 20 63 61 6e 20 62 65 20 6c 6f 77  value can be low
2370: 65 72 65 64 20 28 6f 72 20 72 61 69 73 65 64 29  ered (or raised)
2380: 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
2390: 6e 67 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 6d  ng that the.** m
23a0: 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 20 6d 61  ax_page_count ma
23b0: 63 72 6f 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  cro..*/.#ifndef 
23c0: 53 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f  SQLITE_MAX_PAGE_
23d0: 43 4f 55 4e 54 0a 23 20 64 65 66 69 6e 65 20 53  COUNT.# define S
23e0: 51 4c 49 54 45 5f 4d 41 58 5f 50 41 47 45 5f 43  QLITE_MAX_PAGE_C
23f0: 4f 55 4e 54 20 31 30 37 33 37 34 31 38 32 33 0a  OUNT 1073741823.
2400: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61  #endif../*.** Ma
2410: 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 28 69 6e  ximum length (in
2420: 20 62 79 74 65 73 29 20 6f 66 20 74 68 65 20 70   bytes) of the p
2430: 61 74 74 65 72 6e 20 69 6e 20 61 20 4c 49 4b 45  attern in a LIKE
2440: 20 6f 72 20 47 4c 4f 42 0a 2a 2a 20 6f 70 65 72   or GLOB.** oper
2450: 61 74 6f 72 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  ator..*/.#ifndef
2460: 20 53 51 4c 49 54 45 5f 4d 41 58 5f 4c 49 4b 45   SQLITE_MAX_LIKE
2470: 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 0a  _PATTERN_LENGTH.
2480: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2490: 4d 41 58 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MAX_LIKE_PATTERN
24a0: 5f 4c 45 4e 47 54 48 20 35 30 30 30 30 0a 23 65  _LENGTH 50000.#e
24b0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 4d 61 78 69  ndif../*.** Maxi
24c0: 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
24d0: 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
24e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 76 61 6c  ers..**.** A val
24f0: 75 65 20 6f 66 20 31 20 6d 65 61 6e 73 20 74 68  ue of 1 means th
2500: 61 74 20 61 20 74 72 69 67 67 65 72 20 70 72 6f  at a trigger pro
2510: 67 72 61 6d 20 77 69 6c 6c 20 6e 6f 74 20 62 65  gram will not be
2520: 20 61 62 6c 65 20 74 6f 20 69 74 73 65 6c 66 0a   able to itself.
2530: 2a 2a 20 66 69 72 65 20 61 6e 79 20 74 72 69 67  ** fire any trig
2540: 67 65 72 73 2e 20 41 20 76 61 6c 75 65 20 6f 66  gers. A value of
2550: 20 30 20 6d 65 61 6e 73 20 74 68 61 74 20 6e 6f   0 means that no
2560: 20 74 72 69 67 67 65 72 20 70 72 6f 67 72 61 6d   trigger program
2570: 73 20 61 74 20 61 6c 6c 20 0a 2a 2a 20 6d 61 79  s at all .** may
2580: 20 62 65 20 65 78 65 63 75 74 65 64 2e 0a 2a 2f   be executed..*/
2590: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
25a0: 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MAX_TRIGGER_DEPT
25b0: 48 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  H.# define SQLIT
25c0: 45 5f 4d 41 58 5f 54 52 49 47 47 45 52 5f 44 45  E_MAX_TRIGGER_DE
25d0: 50 54 48 20 31 30 30 30 0a 23 65 6e 64 69 66 0a  PTH 1000.#endif.
25e0: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
25f0: 20 45 6e 64 20 6f 66 20 73 71 6c 69 74 65 4c 69   End of sqliteLi
2600: 6d 69 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  mit.h **********
2610: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
2620: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
2630: 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ./**************
2640: 20 43 6f 6e 74 69 6e 75 69 6e 67 20 77 68 65 72   Continuing wher
2650: 65 20 77 65 20 6c 65 66 74 20 6f 66 66 20 69 6e  e we left off in
2660: 20 73 71 6c 69 74 65 49 6e 74 2e 68 20 2a 2a 2a   sqliteInt.h ***
2670: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  ***************/
2680: 0a 0a 2f 2a 20 44 69 73 61 62 6c 65 20 6e 75 69  ../* Disable nui
2690: 73 61 6e 63 65 20 77 61 72 6e 69 6e 67 73 20 6f  sance warnings o
26a0: 6e 20 42 6f 72 6c 61 6e 64 20 63 6f 6d 70 69 6c  n Borland compil
26b0: 65 72 73 20 2a 2f 0a 23 69 66 20 64 65 66 69 6e  ers */.#if defin
26c0: 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29  ed(__BORLANDC__)
26d0: 0a 23 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 72  .#pragma warn -r
26e0: 63 68 20 2f 2a 20 75 6e 72 65 61 63 68 61 62 6c  ch /* unreachabl
26f0: 65 20 63 6f 64 65 20 2a 2f 0a 23 70 72 61 67 6d  e code */.#pragm
2700: 61 20 77 61 72 6e 20 2d 63 63 63 20 2f 2a 20 43  a warn -ccc /* C
2710: 6f 6e 64 69 74 69 6f 6e 20 69 73 20 61 6c 77 61  ondition is alwa
2720: 79 73 20 74 72 75 65 20 6f 72 20 66 61 6c 73 65  ys true or false
2730: 20 2a 2f 0a 23 70 72 61 67 6d 61 20 77 61 72 6e   */.#pragma warn
2740: 20 2d 61 75 73 20 2f 2a 20 41 73 73 69 67 6e 65   -aus /* Assigne
2750: 64 20 76 61 6c 75 65 20 69 73 20 6e 65 76 65 72  d value is never
2760: 20 75 73 65 64 20 2a 2f 0a 23 70 72 61 67 6d 61   used */.#pragma
2770: 20 77 61 72 6e 20 2d 63 73 75 20 2f 2a 20 43 6f   warn -csu /* Co
2780: 6d 70 61 72 69 6e 67 20 73 69 67 6e 65 64 20 61  mparing signed a
2790: 6e 64 20 75 6e 73 69 67 6e 65 64 20 2a 2f 0a 23  nd unsigned */.#
27a0: 70 72 61 67 6d 61 20 77 61 72 6e 20 2d 73 70 61  pragma warn -spa
27b0: 20 2f 2a 20 53 75 73 70 69 63 69 6f 75 73 20 70   /* Suspicious p
27c0: 6f 69 6e 74 65 72 20 61 72 69 74 68 6d 65 74 69  ointer arithmeti
27d0: 63 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 20  c */.#endif../* 
27e0: 4e 65 65 64 65 64 20 66 6f 72 20 76 61 72 69 6f  Needed for vario
27f0: 75 73 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 2e  us definitions..
2800: 2e 20 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 47 4e  . */.#ifndef _GN
2810: 55 5f 53 4f 55 52 43 45 0a 23 20 64 65 66 69 6e  U_SOURCE.# defin
2820: 65 20 5f 47 4e 55 5f 53 4f 55 52 43 45 0a 23 65  e _GNU_SOURCE.#e
2830: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c  ndif../*.** Incl
2840: 75 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61  ude standard hea
2850: 64 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63  der files as nec
2860: 65 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66  essary.*/.#ifdef
2870: 20 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23   HAVE_STDINT_H.#
2880: 69 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e  include <stdint.
2890: 68 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66  h>.#endif.#ifdef
28a0: 20 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48   HAVE_INTTYPES_H
28b0: 0a 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79  .#include <intty
28c0: 70 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f  pes.h>.#endif../
28d0: 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
28e0: 6e 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  ng macros are us
28f0: 65 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74  ed to cast point
2900: 65 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20  ers to integers 
2910: 61 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20  and.** integers 
2920: 74 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68  to pointers.  Th
2930: 65 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69  e way you do thi
2940: 73 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e  s varies from on
2950: 65 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f  e compiler.** to
2960: 20 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65   the next, so we
2970: 20 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20   have developed 
2980: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65  the following se
2990: 74 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65  t of #if stateme
29a0: 6e 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61  nts.** to genera
29b0: 74 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d  te appropriate m
29c0: 61 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65  acros for a wide
29d0: 20 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c   range of compil
29e0: 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63  ers..**.** The c
29f0: 6f 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 61  orrect "ANSI" wa
2a00: 79 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20  y to do this is 
2a10: 74 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 74  to use the intpt
2a20: 72 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e  r_t type. .** Un
2a30: 66 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61  fortunately, tha
2a40: 74 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74  t typedef is not
2a50: 20 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c   available on al
2a60: 6c 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a  l compilers, or.
2a70: 2a 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 69  ** if it is avai
2a80: 6c 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72  lable, it requir
2a90: 65 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f  es an #include o
2aa0: 66 20 73 70 65 63 69 66 69 63 20 68 65 61 64 65  f specific heade
2ab0: 72 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20  rs.** that vary 
2ac0: 66 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65  from one machine
2ad0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a   to the next..**
2ae0: 0a 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30  .** Ticket #3860
2af0: 3a 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d  :  The llvm-gcc-
2b00: 34 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f  4.2 compiler fro
2b10: 6d 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f  m Apple chokes o
2b20: 6e 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a  n.** the ((void*
2b30: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29  )&((char*)0)[X])
2b40: 20 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74   construct.  But
2b50: 20 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20   MSVC chokes on 
2b60: 28 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a  ((void*)(X))..**
2b70: 20 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64   So we have to d
2b80: 65 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73  efine the macros
2b90: 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61   in different wa
2ba0: 79 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ys depending on 
2bb0: 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e  the.** compiler.
2bc0: 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28  .*/.#if defined(
2bd0: 5f 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f  __PTRDIFF_TYPE__
2be0: 29 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20  )  /* This case 
2bf0: 73 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20  should work for 
2c00: 47 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20  GCC */.# define 
2c10: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54  SQLITE_INT_TO_PT
2c20: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f  R(X)  ((void*)(_
2c30: 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29  _PTRDIFF_TYPE__)
2c40: 28 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51  (X)).# define SQ
2c50: 4c 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28  LITE_PTR_TO_INT(
2c60: 58 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52  X)  ((int)(__PTR
2c70: 44 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29  DIFF_TYPE__)(X))
2c80: 0a 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28  .#elif !defined(
2c90: 5f 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20  __GNUC__)       
2ca0: 2f 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d  /* Works for com
2cb0: 70 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61  pilers other tha
2cc0: 6e 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69  n LLVM */.# defi
2cd0: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f  ne SQLITE_INT_TO
2ce0: 5f 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a  _PTR(X)  ((void*
2cf0: 29 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29  )&((char*)0)[X])
2d00: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2d10: 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20  _PTR_TO_INT(X)  
2d20: 28 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58  ((int)(((char*)X
2d30: 29 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c  )-(char*)0)).#el
2d40: 69 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f  if defined(HAVE_
2d50: 53 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55  STDINT_H)   /* U
2d60: 73 65 20 74 68 69 73 20 63 61 73 65 20 69 66 20  se this case if 
2d70: 77 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 61  we have ANSI hea
2d80: 64 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65  ders */.# define
2d90: 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50   SQLITE_INT_TO_P
2da0: 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28  TR(X)  ((void*)(
2db0: 69 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20  intptr_t)(X)).# 
2dc0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54  define SQLITE_PT
2dd0: 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69  R_TO_INT(X)  ((i
2de0: 6e 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29  nt)(intptr_t)(X)
2df0: 29 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 20  ).#else         
2e00: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e10: 20 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20   /* Generates a 
2e20: 77 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74  warning - but it
2e30: 20 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f   always works */
2e40: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2e50: 5f 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20  _INT_TO_PTR(X)  
2e60: 28 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64  ((void*)(X)).# d
2e70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52  efine SQLITE_PTR
2e80: 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e  _TO_INT(X)  ((in
2e90: 74 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f  t)(X)).#endif../
2ea0: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
2eb0: 54 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f  THREADSAFE macro
2ec0: 20 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 64   must be defined
2ed0: 20 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a   as 0, 1, or 2..
2ee0: 2a 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78  ** 0 means mutex
2ef0: 65 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74  es are permanent
2f00: 6c 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74  ly disable and t
2f10: 68 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65  he library is ne
2f20: 76 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66  ver.** threadsaf
2f30: 65 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20  e.  1 means the 
2f40: 6c 69 62 72 61 72 79 20 69 73 20 73 65 72 69 61  library is seria
2f50: 6c 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 74  lized which is t
2f60: 68 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65  he highest.** le
2f70: 76 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66  vel of threadsaf
2f80: 65 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68  ety.  2 means th
2f90: 65 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c 74  e libary is mult
2fa0: 69 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74  ithreaded - mult
2fb0: 69 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20  iple.** threads 
2fc0: 63 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61  can use SQLite a
2fd0: 73 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f  s long as no two
2fe0: 20 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20   threads try to 
2ff0: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
3000: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3010: 69 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  ion at the same 
3020: 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65  time..**.** Olde
3030: 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  r versions of SQ
3040: 4c 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74  Lite used an opt
3050: 69 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45  ional THREADSAFE
3060: 20 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75   macro..** We su
3070: 70 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c  pport that for l
3080: 65 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64  egacy..*/.#if !d
3090: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48  efined(SQLITE_TH
30a0: 52 45 41 44 53 41 46 45 29 0a 23 69 66 20 64 65  READSAFE).#if de
30b0: 66 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45  fined(THREADSAFE
30c0: 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  ).# define SQLIT
30d0: 45 5f 54 48 52 45 41 44 53 41 46 45 20 54 48 52  E_THREADSAFE THR
30e0: 45 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23 20  EADSAFE.#else.# 
30f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 48  define SQLITE_TH
3100: 52 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49 4d  READSAFE 1 /* IM
3110: 50 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30 39  P: R-07272-22309
3120: 20 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69   */.#endif.#endi
3130: 66 0a 0a 2f 2a 0a 2a 2a 20 50 6f 77 65 72 73 61  f../*.** Powersa
3140: 66 65 20 6f 76 65 72 77 72 69 74 65 20 69 73 20  fe overwrite is 
3150: 6f 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20  on by default.  
3160: 42 75 74 20 63 61 6e 20 62 65 20 74 75 72 6e 65  But can be turne
3170: 64 20 6f 66 66 20 75 73 69 6e 67 0a 2a 2a 20 74  d off using.** t
3180: 68 65 20 2d 44 53 51 4c 49 54 45 5f 50 4f 57 45  he -DSQLITE_POWE
3190: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 3d  RSAFE_OVERWRITE=
31a0: 30 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 6f  0 command-line o
31b0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65  ption..*/.#ifnde
31c0: 66 20 53 51 4c 49 54 45 5f 50 4f 57 45 52 53 41  f SQLITE_POWERSA
31d0: 46 45 5f 4f 56 45 52 57 52 49 54 45 0a 23 20 64  FE_OVERWRITE.# d
31e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 4f 57  efine SQLITE_POW
31f0: 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45  ERSAFE_OVERWRITE
3200: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a   1.#endif../*.**
3210: 20 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46 41   The SQLITE_DEFA
3220: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 20 6d 61  ULT_MEMSTATUS ma
3230: 63 72 6f 20 6d 75 73 74 20 62 65 20 64 65 66 69  cro must be defi
3240: 6e 65 64 20 61 73 20 65 69 74 68 65 72 20 30 20  ned as either 0 
3250: 6f 72 20 31 2e 0a 2a 2a 20 49 74 20 64 65 74 65  or 1..** It dete
3260: 72 6d 69 6e 65 73 20 77 68 65 74 68 65 72 20 6f  rmines whether o
3270: 72 20 6e 6f 74 20 74 68 65 20 66 65 61 74 75 72  r not the featur
3280: 65 73 20 72 65 6c 61 74 65 64 20 74 6f 20 0a 2a  es related to .*
3290: 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
32a0: 4d 45 4d 53 54 41 54 55 53 20 61 72 65 20 61 76  MEMSTATUS are av
32b0: 61 69 6c 61 62 6c 65 20 62 79 20 64 65 66 61 75  ailable by defau
32c0: 6c 74 20 6f 72 20 6e 6f 74 2e 20 54 68 69 73 20  lt or not. This 
32d0: 76 61 6c 75 65 20 63 61 6e 0a 2a 2a 20 62 65 20  value can.** be 
32e0: 6f 76 65 72 72 69 64 64 65 6e 20 61 74 20 72 75  overridden at ru
32f0: 6e 74 69 6d 65 20 75 73 69 6e 67 20 74 68 65 20  ntime using the 
3300: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
3310: 20 41 50 49 2e 0a 2a 2f 0a 23 69 66 20 21 64 65   API..*/.#if !de
3320: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 46  fined(SQLITE_DEF
3330: 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 29 0a  AULT_MEMSTATUS).
3340: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
3350: 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55  DEFAULT_MEMSTATU
3360: 53 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  S 1.#endif../*.*
3370: 2a 20 45 78 61 63 74 6c 79 20 6f 6e 65 20 6f 66  * Exactly one of
3380: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d   the following m
3390: 61 63 72 6f 73 20 6d 75 73 74 20 62 65 20 64 65  acros must be de
33a0: 66 69 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74  fined in order t
33b0: 6f 0a 2a 2a 20 73 70 65 63 69 66 79 20 77 68 69  o.** specify whi
33c0: 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ch memory alloca
33d0: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 74  tion subsystem t
33e0: 6f 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 20 20 20  o use..**.**    
33f0: 20 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d   SQLITE_SYSTEM_M
3400: 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 20 2f  ALLOC          /
3410: 2f 20 55 73 65 20 6e 6f 72 6d 61 6c 20 73 79 73  / Use normal sys
3420: 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 20  tem malloc().** 
3430: 20 20 20 20 53 51 4c 49 54 45 5f 57 49 4e 33 32      SQLITE_WIN32
3440: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20  _MALLOC         
3450: 20 20 2f 2f 20 55 73 65 20 57 69 6e 33 32 20 6e    // Use Win32 n
3460: 61 74 69 76 65 20 68 65 61 70 20 41 50 49 0a 2a  ative heap API.*
3470: 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 5a 45 52  *     SQLITE_ZER
3480: 4f 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20  O_MALLOC        
3490: 20 20 20 20 2f 2f 20 55 73 65 20 61 20 73 74 75      // Use a stu
34a0: 62 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  b allocator that
34b0: 20 61 6c 77 61 79 73 20 66 61 69 6c 73 0a 2a 2a   always fails.**
34c0: 20 20 20 20 20 53 51 4c 49 54 45 5f 4d 45 4d 44       SQLITE_MEMD
34d0: 45 42 55 47 20 20 20 20 20 20 20 20 20 20 20 20  EBUG            
34e0: 20 20 20 2f 2f 20 44 65 62 75 67 67 69 6e 67 20     // Debugging 
34f0: 76 65 72 73 69 6f 6e 20 6f 66 20 73 79 73 74 65  version of syste
3500: 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a 2a 2a  m malloc().**.**
3510: 20 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69 66 20   On Windows, if 
3520: 74 68 65 20 53 51 4c 49 54 45 5f 57 49 4e 33 32  the SQLITE_WIN32
3530: 5f 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41 54 45  _MALLOC_VALIDATE
3540: 20 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e 65   macro is define
3550: 64 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61 73 73  d and the.** ass
3560: 65 72 74 28 29 20 6d 61 63 72 6f 20 69 73 20 65  ert() macro is e
3570: 6e 61 62 6c 65 64 2c 20 65 61 63 68 20 63 61 6c  nabled, each cal
3580: 6c 20 69 6e 74 6f 20 74 68 65 20 57 69 6e 33 32  l into the Win32
3590: 20 6e 61 74 69 76 65 20 68 65 61 70 20 73 75 62   native heap sub
35a0: 73 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c 20 63  system.** will c
35b0: 61 75 73 65 20 48 65 61 70 56 61 6c 69 64 61 74  ause HeapValidat
35c0: 65 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e 20  e to be called. 
35d0: 20 49 66 20 68 65 61 70 20 76 61 6c 69 64 61 74   If heap validat
35e0: 69 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69 6c 2c  ion should fail,
35f0: 20 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e   an.** assertion
3600: 20 77 69 6c 6c 20 62 65 20 74 72 69 67 67 65 72   will be trigger
3610: 65 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74 6f  ed..**.** (Histo
3620: 72 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54 68 65  rical note:  The
3630: 72 65 20 75 73 65 64 20 74 6f 20 62 65 20 73 65  re used to be se
3640: 76 65 72 61 6c 20 6f 74 68 65 72 20 6f 70 74 69  veral other opti
3650: 6f 6e 73 2c 20 62 75 74 20 77 65 27 76 65 0a 2a  ons, but we've.*
3660: 2a 20 70 61 72 65 64 20 69 74 20 64 6f 77 6e 20  * pared it down 
3670: 74 6f 20 6a 75 73 74 20 74 68 65 73 65 20 74 68  to just these th
3680: 72 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66 20 6e  ree.).**.** If n
3690: 6f 6e 65 20 6f 66 20 74 68 65 20 61 62 6f 76 65  one of the above
36a0: 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
36b0: 65 6e 20 73 65 74 20 53 51 4c 49 54 45 5f 53 59  en set SQLITE_SY
36c0: 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73 0a 2a  STEM_MALLOC as.*
36d0: 2a 20 74 68 65 20 64 65 66 61 75 6c 74 2e 0a 2a  * the default..*
36e0: 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 51  /.#if defined(SQ
36f0: 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c  LITE_SYSTEM_MALL
3700: 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66 69 6e 65  OC) \.  + define
3710: 64 28 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d  d(SQLITE_WIN32_M
3720: 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66  ALLOC) \.  + def
3730: 69 6e 65 64 28 53 51 4c 49 54 45 5f 5a 45 52 4f  ined(SQLITE_ZERO
3740: 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64  _MALLOC) \.  + d
3750: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45  efined(SQLITE_ME
3760: 4d 44 45 42 55 47 29 3e 31 0a 23 20 65 72 72 6f  MDEBUG)>1.# erro
3770: 72 20 22 54 77 6f 20 6f 72 20 6d 6f 72 65 20 6f  r "Two or more o
3780: 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  f the following 
3790: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e  compile-time con
37a0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
37b0: 6e 73 5c 0a 20 61 72 65 20 64 65 66 69 6e 65 64  ns\. are defined
37c0: 20 62 75 74 20 61 74 20 6d 6f 73 74 20 6f 6e 65   but at most one
37d0: 20 69 73 20 61 6c 6c 6f 77 65 64 3a 5c 0a 20 53   is allowed:\. S
37e0: 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c  QLITE_SYSTEM_MAL
37f0: 4c 4f 43 2c 20 53 51 4c 49 54 45 5f 57 49 4e 33  LOC, SQLITE_WIN3
3800: 32 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 45  2_MALLOC, SQLITE
3810: 5f 4d 45 4d 44 45 42 55 47 2c 5c 0a 20 53 51 4c  _MEMDEBUG,\. SQL
3820: 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 22  ITE_ZERO_MALLOC"
3830: 0a 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69  .#endif.#if defi
3840: 6e 65 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45  ned(SQLITE_SYSTE
3850: 4d 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20  M_MALLOC) \.  + 
3860: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 57  defined(SQLITE_W
3870: 49 4e 33 32 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20  IN32_MALLOC) \. 
3880: 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54   + defined(SQLIT
3890: 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 29 20 5c  E_ZERO_MALLOC) \
38a0: 0a 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c  .  + defined(SQL
38b0: 49 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d 3d 30  ITE_MEMDEBUG)==0
38c0: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
38d0: 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 31  _SYSTEM_MALLOC 1
38e0: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49  .#endif../*.** I
38f0: 66 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f  f SQLITE_MALLOC_
3900: 53 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20 6e 6f  SOFT_LIMIT is no
3910: 74 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 79  t zero, then try
3920: 20 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a 2a 20   to keep the.** 
3930: 73 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20  sizes of memory 
3940: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65 6c 6f  allocations belo
3950: 77 20 74 68 69 73 20 76 61 6c 75 65 20 77 68 65  w this value whe
3960: 72 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2f 0a  re possible..*/.
3970: 23 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c  #if !defined(SQL
3980: 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f  ITE_MALLOC_SOFT_
3990: 4c 49 4d 49 54 29 0a 23 20 64 65 66 69 6e 65 20  LIMIT).# define 
39a0: 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f  SQLITE_MALLOC_SO
39b0: 46 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a 23 65  FT_LIMIT 1024.#e
39c0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65 20 6e  ndif../*.** We n
39d0: 65 65 64 20 74 6f 20 64 65 66 69 6e 65 20 5f 58  eed to define _X
39e0: 4f 50 45 4e 5f 53 4f 55 52 43 45 20 61 73 20 66  OPEN_SOURCE as f
39f0: 6f 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65 72 20  ollows in order 
3a00: 74 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72 65 63  to enable.** rec
3a10: 75 72 73 69 76 65 20 6d 75 74 65 78 65 73 20 6f  ursive mutexes o
3a20: 6e 20 6d 6f 73 74 20 55 6e 69 78 20 73 79 73 74  n most Unix syst
3a30: 65 6d 73 2e 20 20 42 75 74 20 4d 61 63 20 4f 53  ems.  But Mac OS
3a40: 20 58 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e   X is different.
3a50: 0a 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e 5f 53  .** The _XOPEN_S
3a60: 4f 55 52 43 45 20 64 65 66 69 6e 65 20 63 61 75  OURCE define cau
3a70: 73 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f 72  ses problems for
3a80: 20 4d 61 63 20 4f 53 20 58 20 77 65 20 61 72 65   Mac OS X we are
3a90: 20 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69 74 20   told,.** so it 
3aa0: 69 73 20 6f 6d 69 74 74 65 64 20 74 68 65 72 65  is omitted there
3ab0: 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32  .  See ticket #2
3ac0: 36 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74 65 72  673..**.** Later
3ad0: 20 77 65 20 6c 65 61 72 6e 20 74 68 61 74 20 5f   we learn that _
3ae0: 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69 73 20  XOPEN_SOURCE is 
3af0: 70 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f 72 72  poorly or incorr
3b00: 65 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ectly.** impleme
3b10: 6e 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73 79 73  nted on some sys
3b20: 74 65 6d 73 2e 20 20 53 6f 20 77 65 20 61 76 6f  tems.  So we avo
3b30: 69 64 20 64 65 66 69 6e 69 6e 67 20 69 74 20 61  id defining it a
3b40: 74 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74 20 69  t all.** if it i
3b50: 73 20 61 6c 72 65 61 64 79 20 64 65 66 69 6e 65  s already define
3b60: 64 20 6f 72 20 69 66 20 69 74 20 69 73 20 75 6e  d or if it is un
3b70: 6e 65 65 64 65 64 20 62 65 63 61 75 73 65 20 77  needed because w
3b80: 65 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64 6f 69  e are.** not doi
3b90: 6e 67 20 61 20 74 68 72 65 61 64 73 61 66 65 20  ng a threadsafe 
3ba0: 62 75 69 6c 64 2e 20 20 54 69 63 6b 65 74 20 23  build.  Ticket #
3bb0: 32 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2681..**.** See 
3bc0: 61 6c 73 6f 20 74 69 63 6b 65 74 20 23 32 37 34  also ticket #274
3bd0: 31 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e  1..*/.#if !defin
3be0: 65 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45  ed(_XOPEN_SOURCE
3bf0: 29 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 5f  ) && !defined(__
3c00: 44 41 52 57 49 4e 5f 5f 29 20 26 26 20 21 64 65  DARWIN__) && !de
3c10: 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45 5f 5f 29  fined(__APPLE__)
3c20: 20 26 26 20 53 51 4c 49 54 45 5f 54 48 52 45 41   && SQLITE_THREA
3c30: 44 53 41 46 45 0a 23 20 20 64 65 66 69 6e 65 20  DSAFE.#  define 
3c40: 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20 35 30  _XOPEN_SOURCE 50
3c50: 30 20 20 2f 2a 20 4e 65 65 64 65 64 20 74 6f 20  0  /* Needed to 
3c60: 65 6e 61 62 6c 65 20 70 74 68 72 65 61 64 20 72  enable pthread r
3c70: 65 63 75 72 73 69 76 65 20 6d 75 74 65 78 65 73  ecursive mutexes
3c80: 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a   */.#endif../*.*
3c90: 2a 20 54 68 65 20 54 43 4c 20 68 65 61 64 65 72  * The TCL header
3ca0: 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65 65 64 65  s are only neede
3cb0: 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e 67  d when compiling
3cc0: 20 74 68 65 20 54 43 4c 20 62 69 6e 64 69 6e 67   the TCL binding
3cd0: 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65  s..*/.#if define
3ce0: 64 28 53 51 4c 49 54 45 5f 54 43 4c 29 20 7c 7c  d(SQLITE_TCL) ||
3cf0: 20 64 65 66 69 6e 65 64 28 54 43 4c 53 48 29 0a   defined(TCLSH).
3d00: 23 20 69 6e 63 6c 75 64 65 20 3c 74 63 6c 2e 68  # include <tcl.h
3d10: 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  >.#endif../*.** 
3d20: 4e 44 45 42 55 47 20 61 6e 64 20 53 51 4c 49 54  NDEBUG and SQLIT
3d30: 45 5f 44 45 42 55 47 20 61 72 65 20 6f 70 70 6f  E_DEBUG are oppo
3d40: 73 69 74 65 73 2e 20 20 49 74 20 73 68 6f 75 6c  sites.  It shoul
3d50: 64 20 61 6c 77 61 79 73 20 62 65 20 74 72 75 65  d always be true
3d60: 20 74 68 61 74 0a 2a 2a 20 64 65 66 69 6e 65 64   that.** defined
3d70: 28 4e 44 45 42 55 47 29 3d 3d 21 64 65 66 69 6e  (NDEBUG)==!defin
3d80: 65 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29  ed(SQLITE_DEBUG)
3d90: 2e 20 20 49 66 20 74 68 69 73 20 69 73 20 6e 6f  .  If this is no
3da0: 74 20 63 75 72 72 65 6e 74 6c 79 20 74 72 75 65  t currently true
3db0: 2c 0a 2a 2a 20 6d 61 6b 65 20 69 74 20 74 72 75  ,.** make it tru
3dc0: 65 20 62 79 20 64 65 66 69 6e 69 6e 67 20 6f 72  e by defining or
3dd0: 20 75 6e 64 65 66 69 6e 69 6e 67 20 4e 44 45 42   undefining NDEB
3de0: 55 47 2e 0a 2a 2a 0a 2a 2a 20 53 65 74 74 69 6e  UG..**.** Settin
3df0: 67 20 4e 44 45 42 55 47 20 6d 61 6b 65 73 20 74  g NDEBUG makes t
3e00: 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c 65 72 20  he code smaller 
3e10: 61 6e 64 20 72 75 6e 20 66 61 73 74 65 72 20 62  and run faster b
3e20: 79 20 64 69 73 61 62 6c 69 6e 67 20 74 68 65 0a  y disabling the.
3e30: 2a 2a 20 6e 75 6d 62 65 72 20 61 73 73 65 72 74  ** number assert
3e40: 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  () statements in
3e50: 20 74 68 65 20 63 6f 64 65 2e 20 20 53 6f 20 77   the code.  So w
3e60: 65 20 77 61 6e 74 20 74 68 65 20 64 65 66 61 75  e want the defau
3e70: 6c 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 74 6f 20  lt action.** to 
3e80: 62 65 20 66 6f 72 20 4e 44 45 42 55 47 20 74 6f  be for NDEBUG to
3e90: 20 62 65 20 73 65 74 20 61 6e 64 20 4e 44 45 42   be set and NDEB
3ea0: 55 47 20 74 6f 20 62 65 20 75 6e 64 65 66 69 6e  UG to be undefin
3eb0: 65 64 20 6f 6e 6c 79 20 69 66 20 53 51 4c 49 54  ed only if SQLIT
3ec0: 45 5f 44 45 42 55 47 0a 2a 2a 20 69 73 20 73 65  E_DEBUG.** is se
3ed0: 74 2e 20 20 54 68 75 73 20 4e 44 45 42 55 47 20  t.  Thus NDEBUG 
3ee0: 62 65 63 6f 6d 65 73 20 61 6e 20 6f 70 74 2d 69  becomes an opt-i
3ef0: 6e 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 6e  n rather than an
3f00: 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66 65 61 74   opt-out.** feat
3f10: 75 72 65 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66  ure..*/.#if !def
3f20: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 26 26 20  ined(NDEBUG) && 
3f30: 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f  !defined(SQLITE_
3f40: 44 45 42 55 47 29 20 0a 23 20 64 65 66 69 6e 65  DEBUG) .# define
3f50: 20 4e 44 45 42 55 47 20 31 0a 23 65 6e 64 69 66   NDEBUG 1.#endif
3f60: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 4e 44 45  .#if defined(NDE
3f70: 42 55 47 29 20 26 26 20 64 65 66 69 6e 65 64 28  BUG) && defined(
3f80: 53 51 4c 49 54 45 5f 44 45 42 55 47 29 0a 23 20  SQLITE_DEBUG).# 
3f90: 75 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 65 6e  undef NDEBUG.#en
3fa0: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74  dif../*.** The t
3fb0: 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20  estcase() macro 
3fc0: 69 73 20 75 73 65 64 20 74 6f 20 61 69 64 20 69  is used to aid i
3fd0: 6e 20 63 6f 76 65 72 61 67 65 20 74 65 73 74 69  n coverage testi
3fe0: 6e 67 2e 20 20 57 68 65 6e 20 0a 2a 2a 20 64 6f  ng.  When .** do
3ff0: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73  ing coverage tes
4000: 74 69 6e 67 2c 20 74 68 65 20 63 6f 6e 64 69 74  ting, the condit
4010: 69 6f 6e 20 69 6e 73 69 64 65 20 74 68 65 20 61  ion inside the a
4020: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 65  rgument to.** te
4030: 73 74 63 61 73 65 28 29 20 6d 75 73 74 20 62 65  stcase() must be
4040: 20 65 76 61 6c 75 61 74 65 64 20 62 6f 74 68 20   evaluated both 
4050: 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 20 69  true and false i
4060: 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 67 65  n order to.** ge
4070: 74 20 66 75 6c 6c 20 62 72 61 6e 63 68 20 63 6f  t full branch co
4080: 76 65 72 61 67 65 2e 20 20 54 68 65 20 74 65 73  verage.  The tes
4090: 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20 69 73  tcase() macro is
40a0: 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 74 6f 20   inserted.** to 
40b0: 68 65 6c 70 20 65 6e 73 75 72 65 20 61 64 65 71  help ensure adeq
40c0: 75 61 74 65 20 74 65 73 74 20 63 6f 76 65 72 61  uate test covera
40d0: 67 65 20 69 6e 20 70 6c 61 63 65 73 20 77 68 65  ge in places whe
40e0: 72 65 20 73 69 6d 70 6c 65 0a 2a 2a 20 63 6f 6e  re simple.** con
40f0: 64 69 74 69 6f 6e 2f 64 65 63 69 73 69 6f 6e 20  dition/decision 
4100: 63 6f 76 65 72 61 67 65 20 69 73 20 69 6e 61 64  coverage is inad
4110: 65 71 75 61 74 65 2e 20 20 46 6f 72 20 65 78 61  equate.  For exa
4120: 6d 70 6c 65 2c 20 74 65 73 74 63 61 73 65 28 29  mple, testcase()
4130: 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64 20  .** can be used 
4140: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 62 6f 75  to make sure bou
4150: 6e 64 61 72 79 20 76 61 6c 75 65 73 20 61 72 65  ndary values are
4160: 20 74 65 73 74 65 64 2e 20 20 46 6f 72 0a 2a 2a   tested.  For.**
4170: 20 62 69 74 6d 61 73 6b 20 74 65 73 74 73 2c 20   bitmask tests, 
4180: 74 65 73 74 63 61 73 65 28 29 20 63 61 6e 20 62  testcase() can b
4190: 65 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 73  e used to make s
41a0: 75 72 65 20 65 61 63 68 20 62 69 74 0a 2a 2a 20  ure each bit.** 
41b0: 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74 20 61  is significant a
41c0: 6e 64 20 75 73 65 64 20 61 74 20 6c 65 61 73 74  nd used at least
41d0: 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 77 69 74 63   once.  On switc
41e0: 68 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  h statements.** 
41f0: 77 68 65 72 65 20 6d 75 6c 74 69 70 6c 65 20 63  where multiple c
4200: 61 73 65 73 20 67 6f 20 74 6f 20 74 68 65 20 73  ases go to the s
4210: 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20 63 6f 64  ame block of cod
4220: 65 2c 20 74 65 73 74 63 61 73 65 28 29 0a 2a 2a  e, testcase().**
4230: 20 63 61 6e 20 69 6e 73 75 72 65 20 74 68 61 74   can insure that
4240: 20 61 6c 6c 20 63 61 73 65 73 20 61 72 65 20 65   all cases are e
4250: 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a 2f 0a  valuated..**.*/.
4260: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 43 4f  #ifdef SQLITE_CO
4270: 56 45 52 41 47 45 5f 54 45 53 54 0a 53 51 4c 49  VERAGE_TEST.SQLI
4280: 54 45 5f 50 52 49 56 41 54 45 20 20 20 76 6f 69  TE_PRIVATE   voi
4290: 64 20 73 71 6c 69 74 65 33 43 6f 76 65 72 61 67  d sqlite3Coverag
42a0: 65 28 69 6e 74 29 3b 0a 23 20 64 65 66 69 6e 65  e(int);.# define
42b0: 20 74 65 73 74 63 61 73 65 28 58 29 20 20 69 66   testcase(X)  if
42c0: 28 20 58 20 29 7b 20 73 71 6c 69 74 65 33 43 6f  ( X ){ sqlite3Co
42d0: 76 65 72 61 67 65 28 5f 5f 4c 49 4e 45 5f 5f 29  verage(__LINE__)
42e0: 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  ; }.#else.# defi
42f0: 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 0a 23  ne testcase(X).#
4300: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
4310: 20 54 45 53 54 4f 4e 4c 59 20 6d 61 63 72 6f 20   TESTONLY macro 
4320: 69 73 20 75 73 65 64 20 74 6f 20 65 6e 63 6c 6f  is used to enclo
4330: 73 65 20 76 61 72 69 61 62 6c 65 20 64 65 63 6c  se variable decl
4340: 61 72 61 74 69 6f 6e 73 20 6f 72 0a 2a 2a 20 6f  arations or.** o
4350: 74 68 65 72 20 62 69 74 73 20 6f 66 20 63 6f 64  ther bits of cod
4360: 65 20 74 68 61 74 20 61 72 65 20 6e 65 65 64 65  e that are neede
4370: 64 20 74 6f 20 73 75 70 70 6f 72 74 20 74 68 65  d to support the
4380: 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 77 69   arguments.** wi
4390: 74 68 69 6e 20 74 65 73 74 63 61 73 65 28 29 20  thin testcase() 
43a0: 61 6e 64 20 61 73 73 65 72 74 28 29 20 6d 61 63  and assert() mac
43b0: 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66  ros..*/.#if !def
43c0: 69 6e 65 64 28 4e 44 45 42 55 47 29 20 7c 7c 20  ined(NDEBUG) || 
43d0: 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 43  defined(SQLITE_C
43e0: 4f 56 45 52 41 47 45 5f 54 45 53 54 29 0a 23 20  OVERAGE_TEST).# 
43f0: 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28  define TESTONLY(
4400: 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65  X)  X.#else.# de
4410: 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28 58 29  fine TESTONLY(X)
4420: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 53  .#endif../*.** S
4430: 6f 6d 65 74 69 6d 65 73 20 77 65 20 6e 65 65 64  ometimes we need
4440: 20 61 20 73 6d 61 6c 6c 20 61 6d 6f 75 6e 74 20   a small amount 
4450: 6f 66 20 63 6f 64 65 20 73 75 63 68 20 61 73 20  of code such as 
4460: 61 20 76 61 72 69 61 62 6c 65 20 69 6e 69 74 69  a variable initi
4470: 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20  alization.** to 
4480: 73 65 74 75 70 20 66 6f 72 20 61 20 6c 61 74 65  setup for a late
4490: 72 20 61 73 73 65 72 74 28 29 20 73 74 61 74 65  r assert() state
44a0: 6d 65 6e 74 2e 20 20 57 65 20 64 6f 20 6e 6f 74  ment.  We do not
44b0: 20 77 61 6e 74 20 74 68 69 73 20 63 6f 64 65 20   want this code 
44c0: 74 6f 0a 2a 2a 20 61 70 70 65 61 72 20 77 68 65  to.** appear whe
44d0: 6e 20 61 73 73 65 72 74 28 29 20 69 73 20 64 69  n assert() is di
44e0: 73 61 62 6c 65 64 2e 20 20 54 68 65 20 66 6f 6c  sabled.  The fol
44f0: 6c 6f 77 69 6e 67 20 6d 61 63 72 6f 20 69 73 20  lowing macro is 
4500: 74 68 65 72 65 66 6f 72 65 0a 2a 2a 20 75 73 65  therefore.** use
4510: 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74 68 61  d to contain tha
4520: 74 20 73 65 74 75 70 20 63 6f 64 65 2e 20 20 54  t setup code.  T
4530: 68 65 20 22 56 56 41 22 20 61 63 72 6f 6e 79 6d  he "VVA" acronym
4540: 20 73 74 61 6e 64 73 20 66 6f 72 0a 2a 2a 20 22   stands for.** "
4550: 56 65 72 69 66 69 63 61 74 69 6f 6e 2c 20 56 61  Verification, Va
4560: 6c 69 64 61 74 69 6f 6e 2c 20 61 6e 64 20 41 63  lidation, and Ac
4570: 63 72 65 64 69 74 61 74 69 6f 6e 22 2e 20 20 49  creditation".  I
4580: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
4590: 68 65 0a 2a 2a 20 63 6f 64 65 20 77 69 74 68 69  he.** code withi
45a0: 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 20 77 69 6c  n VVA_ONLY() wil
45b0: 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 75 72 69 6e  l only run durin
45c0: 67 20 76 65 72 69 66 69 63 61 74 69 6f 6e 20 70  g verification p
45d0: 72 6f 63 65 73 73 65 73 2e 0a 2a 2f 0a 23 69 66  rocesses..*/.#if
45e0: 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 20 64 65  ndef NDEBUG.# de
45f0: 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29  fine VVA_ONLY(X)
4600: 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65 66 69    X.#else.# defi
4610: 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29 0a 23  ne VVA_ONLY(X).#
4620: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
4630: 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45 56 45   ALWAYS and NEVE
4640: 52 20 6d 61 63 72 6f 73 20 73 75 72 72 6f 75 6e  R macros surroun
4650: 64 20 62 6f 6f 6c 65 61 6e 20 65 78 70 72 65 73  d boolean expres
4660: 73 69 6f 6e 73 20 77 68 69 63 68 20 0a 2a 2a 20  sions which .** 
4670: 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20  are intended to 
4680: 61 6c 77 61 79 73 20 62 65 20 74 72 75 65 20 6f  always be true o
4690: 72 20 66 61 6c 73 65 2c 20 72 65 73 70 65 63 74  r false, respect
46a0: 69 76 65 6c 79 2e 20 20 53 75 63 68 0a 2a 2a 20  ively.  Such.** 
46b0: 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 75 6c  expressions coul
46c0: 64 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72 6f  d be omitted fro
46d0: 6d 20 74 68 65 20 63 6f 64 65 20 63 6f 6d 70 6c  m the code compl
46e0: 65 74 65 6c 79 2e 20 20 42 75 74 20 74 68 65 79  etely.  But they
46f0: 0a 2a 2a 20 61 72 65 20 69 6e 63 6c 75 64 65 64  .** are included
4700: 20 69 6e 20 61 20 66 65 77 20 63 61 73 65 73 20   in a few cases 
4710: 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 68 61  in order to enha
4720: 6e 63 65 20 74 68 65 20 72 65 73 69 6c 69 65 6e  nce the resilien
4730: 63 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20  ce.** of SQLite 
4740: 74 6f 20 75 6e 65 78 70 65 63 74 65 64 20 62 65  to unexpected be
4750: 68 61 76 69 6f 72 20 2d 20 74 6f 20 6d 61 6b 65  havior - to make
4760: 20 74 68 65 20 63 6f 64 65 20 22 73 65 6c 66 2d   the code "self-
4770: 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 6f 72 20 22  healing".** or "
4780: 64 75 63 74 69 6c 65 22 20 72 61 74 68 65 72 20  ductile" rather 
4790: 74 68 61 6e 20 62 65 69 6e 67 20 22 62 72 69 74  than being "brit
47a0: 74 6c 65 22 20 61 6e 64 20 63 72 61 73 68 69 6e  tle" and crashin
47b0: 67 20 61 74 20 74 68 65 20 66 69 72 73 74 0a 2a  g at the first.*
47c0: 2a 20 68 69 6e 74 20 6f 66 20 75 6e 70 6c 61 6e  * hint of unplan
47d0: 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a  ned behavior..**
47e0: 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
47f0: 64 73 2c 20 41 4c 57 41 59 53 20 61 6e 64 20 4e  ds, ALWAYS and N
4800: 45 56 45 52 20 61 72 65 20 61 64 64 65 64 20 66  EVER are added f
4810: 6f 72 20 64 65 66 65 6e 73 69 76 65 20 63 6f 64  or defensive cod
4820: 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 64 6f  e..**.** When do
4830: 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74 65 73  ing coverage tes
4840: 74 69 6e 67 20 41 4c 57 41 59 53 20 61 6e 64 20  ting ALWAYS and 
4850: 4e 45 56 45 52 20 61 72 65 20 68 61 72 64 2d 63  NEVER are hard-c
4860: 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 65 20 74 72  oded to.** be tr
4870: 75 65 20 61 6e 64 20 66 61 6c 73 65 20 73 6f 20  ue and false so 
4880: 74 68 61 74 20 74 68 65 20 75 6e 72 65 61 63 68  that the unreach
4890: 61 62 6c 65 20 63 6f 64 65 20 74 68 65 6e 20 73  able code then s
48a0: 70 65 63 69 66 79 20 77 69 6c 6c 0a 2a 2a 20 6e  pecify will.** n
48b0: 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20 61 73  ot be counted as
48c0: 20 75 6e 74 65 73 74 65 64 20 63 6f 64 65 2e 0a   untested code..
48d0: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53  */.#if defined(S
48e0: 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 45 5f 54  QLITE_COVERAGE_T
48f0: 45 53 54 29 0a 23 20 64 65 66 69 6e 65 20 41 4c  EST).# define AL
4900: 57 41 59 53 28 58 29 20 20 20 20 20 20 28 31 29  WAYS(X)      (1)
4910: 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52 28  .# define NEVER(
4920: 58 29 20 20 20 20 20 20 20 28 30 29 0a 23 65 6c  X)       (0).#el
4930: 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44 45 42  if !defined(NDEB
4940: 55 47 29 0a 23 20 64 65 66 69 6e 65 20 41 4c 57  UG).# define ALW
4950: 41 59 53 28 58 29 20 20 20 20 20 20 28 28 58 29  AYS(X)      ((X)
4960: 3f 31 3a 28 61 73 73 65 72 74 28 30 29 2c 30 29  ?1:(assert(0),0)
4970: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52  ).# define NEVER
4980: 28 58 29 20 20 20 20 20 20 20 28 28 58 29 3f 28  (X)       ((X)?(
4990: 61 73 73 65 72 74 28 30 29 2c 31 29 3a 30 29 0a  assert(0),1):0).
49a0: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 41  #else.# define A
49b0: 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28 58  LWAYS(X)      (X
49c0: 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45 52  ).# define NEVER
49d0: 28 58 29 20 20 20 20 20 20 20 28 58 29 0a 23 65  (X)       (X).#e
49e0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 52 65 74 75  ndif../*.** Retu
49f0: 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  rn true (non-zer
4a00: 6f 29 20 69 66 20 74 68 65 20 69 6e 70 75 74 20  o) if the input 
4a10: 69 73 20 61 20 69 6e 74 65 67 65 72 20 74 68 61  is a integer tha
4a20: 74 20 69 73 20 74 6f 6f 20 6c 61 72 67 65 0a 2a  t is too large.*
4a30: 2a 20 74 6f 20 66 69 74 20 69 6e 20 33 32 2d 62  * to fit in 32-b
4a40: 69 74 73 2e 20 20 54 68 69 73 20 6d 61 63 72 6f  its.  This macro
4a50: 20 69 73 20 75 73 65 64 20 69 6e 73 69 64 65 20   is used inside 
4a60: 6f 66 20 76 61 72 69 6f 75 73 20 74 65 73 74 63  of various testc
4a70: 61 73 65 28 29 0a 2a 2a 20 6d 61 63 72 6f 73 20  ase().** macros 
4a80: 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20 77  to verify that w
4a90: 65 20 68 61 76 65 20 74 65 73 74 65 64 20 53 51  e have tested SQ
4aa0: 4c 69 74 65 20 66 6f 72 20 6c 61 72 67 65 2d 66  Lite for large-f
4ab0: 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a 2a 2f 0a  ile support..*/.
4ac0: 23 64 65 66 69 6e 65 20 49 53 5f 42 49 47 5f 49  #define IS_BIG_I
4ad0: 4e 54 28 58 29 20 20 28 28 28 58 29 26 7e 28 69  NT(X)  (((X)&~(i
4ae0: 36 34 29 30 78 66 66 66 66 66 66 66 66 29 21 3d  64)0xffffffff)!=
4af0: 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 6d 61  0)../*.** The ma
4b00: 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 28 29 20 69  cro unlikely() i
4b10: 73 20 61 20 68 69 6e 74 20 74 68 61 74 20 73 75  s a hint that su
4b20: 72 72 6f 75 6e 64 73 20 61 20 62 6f 6f 6c 65 61  rrounds a boolea
4b30: 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
4b40: 74 68 61 74 20 69 73 20 75 73 75 61 6c 6c 79 20  that is usually 
4b50: 66 61 6c 73 65 2e 20 20 4d 61 63 72 6f 20 6c 69  false.  Macro li
4b60: 6b 65 6c 79 28 29 20 73 75 72 72 6f 75 6e 64 73  kely() surrounds
4b70: 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 65 78  .** a boolean ex
4b80: 70 72 65 73 73 69 6f 6e 20 74 68 61 74 20 69 73  pression that is
4b90: 20 75 73 75 61 6c 6c 79 20 74 72 75 65 2e 20 20   usually true.  
4ba0: 47 43 43 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  GCC is able to.*
4bb0: 2a 20 75 73 65 20 74 68 65 73 65 20 68 69 6e 74  * use these hint
4bc0: 73 20 74 6f 20 67 65 6e 65 72 61 74 65 20 62 65  s to generate be
4bd0: 74 74 65 72 20 63 6f 64 65 2c 20 73 6f 6d 65 74  tter code, somet
4be0: 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66  imes..*/.#if def
4bf0: 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29 20 26  ined(__GNUC__) &
4c00: 26 20 30 0a 23 20 64 65 66 69 6e 65 20 6c 69 6b  & 0.# define lik
4c10: 65 6c 79 28 58 29 20 20 20 20 5f 5f 62 75 69 6c  ely(X)    __buil
4c20: 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 31  tin_expect((X),1
4c30: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b  ).# define unlik
4c40: 65 6c 79 28 58 29 20 20 5f 5f 62 75 69 6c 74 69  ely(X)  __builti
4c50: 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 30 29 0a  n_expect((X),0).
4c60: 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 6c  #else.# define l
4c70: 69 6b 65 6c 79 28 58 29 20 20 20 20 21 21 28 58  ikely(X)    !!(X
4c80: 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c 69 6b  ).# define unlik
4c90: 65 6c 79 28 58 29 20 20 21 21 28 58 29 0a 23 65  ely(X)  !!(X).#e
4ca0: 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  ndif../*********
4cb0: 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20 73 71  ***** Include sq
4cc0: 6c 69 74 65 33 2e 68 20 69 6e 20 74 68 65 20 6d  lite3.h in the m
4cd0: 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74 65 49  iddle of sqliteI
4ce0: 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  nt.h ***********
4cf0: 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****/./*********
4d00: 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69 6c 65  ***** Begin file
4d10: 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a 2a 2a   sqlite3.h *****
4d20: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d30: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d40: 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30 30 31  ****/./*.** 2001
4d50: 20 53 65 70 74 65 6d 62 65 72 20 31 35 0a 2a 2a   September 15.**
4d60: 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 20 64  .** The author d
4d70: 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 72 69 67  isclaims copyrig
4d80: 68 74 20 74 6f 20 74 68 69 73 20 73 6f 75 72 63  ht to this sourc
4d90: 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c 61 63  e code.  In plac
4da0: 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61 6c 20  e of.** a legal 
4db0: 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 69 73 20  notice, here is 
4dc0: 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a 0a 2a  a blessing:.**.*
4dd0: 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 64 6f 20  *    May you do 
4de0: 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65 76 69  good and not evi
4df0: 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  l..**    May you
4e00: 20 66 69 6e 64 20 66 6f 72 67 69 76 65 6e 65 73   find forgivenes
4e10: 73 20 66 6f 72 20 79 6f 75 72 73 65 6c 66 20 61  s for yourself a
4e20: 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 68 65 72  nd forgive other
4e30: 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75  s..**    May you
4e40: 20 73 68 61 72 65 20 66 72 65 65 6c 79 2c 20 6e   share freely, n
4e50: 65 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f 72 65  ever taking more
4e60: 20 74 68 61 6e 20 79 6f 75 20 67 69 76 65 2e 0a   than you give..
4e70: 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  **.*************
4e80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4e90: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ea0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4eb0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a 2a 20  ************.** 
4ec0: 54 68 69 73 20 68 65 61 64 65 72 20 66 69 6c 65  This header file
4ed0: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
4ee0: 65 72 66 61 63 65 20 74 68 61 74 20 74 68 65 20  erface that the 
4ef0: 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 0a 2a  SQLite library.*
4f00: 2a 20 70 72 65 73 65 6e 74 73 20 74 6f 20 63 6c  * presents to cl
4f10: 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 2e 20 20  ient programs.  
4f20: 49 66 20 61 20 43 2d 66 75 6e 63 74 69 6f 6e 2c  If a C-function,
4f30: 20 73 74 72 75 63 74 75 72 65 2c 20 64 61 74 61   structure, data
4f40: 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6e 73  type,.** or cons
4f50: 74 61 6e 74 20 64 65 66 69 6e 69 74 69 6f 6e 20  tant definition 
4f60: 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61 72 20  does not appear 
4f70: 69 6e 20 74 68 69 73 20 66 69 6c 65 2c 20 74 68  in this file, th
4f80: 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e 6f 74 20  en it is.** not 
4f90: 61 20 70 75 62 6c 69 73 68 65 64 20 41 50 49 20  a published API 
4fa0: 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 20 73 75  of SQLite, is su
4fb0: 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20  bject to change 
4fc0: 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74 69 63  without.** notic
4fd0: 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f  e, and should no
4fe0: 74 20 62 65 20 72 65 66 65 72 65 6e 63 65 64 20  t be referenced 
4ff0: 62 79 20 70 72 6f 67 72 61 6d 73 20 74 68 61 74  by programs that
5000: 20 75 73 65 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a   use SQLite..**.
5010: 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 64  ** Some of the d
5020: 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 61 74 20  efinitions that 
5030: 61 72 65 20 69 6e 20 74 68 69 73 20 66 69 6c 65  are in this file
5040: 20 61 72 65 20 6d 61 72 6b 65 64 20 61 73 0a 2a   are marked as.*
5050: 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 61 6c 22  * "experimental"
5060: 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 61 6c 20  .  Experimental 
5070: 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
5080: 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a 20 66  ormally new.** f
5090: 65 61 74 75 72 65 73 20 72 65 63 65 6e 74 6c 79  eatures recently
50a0: 20 61 64 64 65 64 20 74 6f 20 53 51 4c 69 74 65   added to SQLite
50b0: 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 61 6e 74  .  We do not ant
50c0: 69 63 69 70 61 74 65 20 63 68 61 6e 67 65 73 0a  icipate changes.
50d0: 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d 65 6e 74  ** to experiment
50e0: 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20 62 75  al interfaces bu
50f0: 74 20 72 65 73 65 72 76 65 20 74 68 65 20 72 69  t reserve the ri
5100: 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d 69 6e 6f  ght to make mino
5110: 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 66 20  r changes.** if 
5120: 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f 6d 20  experience from 
5130: 75 73 65 20 22 69 6e 20 74 68 65 20 77 69 6c 64  use "in the wild
5140: 22 20 73 75 67 67 65 73 74 20 73 75 63 68 20 63  " suggest such c
5150: 68 61 6e 67 65 73 20 61 72 65 20 70 72 75 64 65  hanges are prude
5160: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6f 66  nt..**.** The of
5170: 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75 61 67  ficial C-languag
5180: 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74 61 74  e API documentat
5190: 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65 20 69  ion for SQLite i
51a0: 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66 72 6f  s derived.** fro
51b0: 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20 74 68  m comments in th
51c0: 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73 20 66  is file.  This f
51d0: 69 6c 65 20 69 73 20 74 68 65 20 61 75 74 68 6f  ile is the autho
51e0: 72 69 74 61 74 69 76 65 20 73 6f 75 72 63 65 0a  ritative source.
51f0: 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69 74 65  ** on how SQLite
5200: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
5210: 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65 72 61  suppose to opera
5220: 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6e 61  te..**.** The na
5230: 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  me of this file 
5240: 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72 61 74  under configurat
5250: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 69  ion management i
5260: 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e 22 2e  s "sqlite.h.in".
5270: 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69 6c 65  .** The makefile
5280: 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69 6e 6f   makes some mino
5290: 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 69  r changes to thi
52a0: 73 20 66 69 6c 65 20 28 73 75 63 68 20 61 73 20  s file (such as 
52b0: 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74 68 65  inserting.** the
52c0: 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 29   version number)
52d0: 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69 74 73   and changes its
52e0: 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69 74 65   name to "sqlite
52f0: 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72 74 20  3.h" as.** part 
5300: 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70 72 6f  of the build pro
5310: 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  cess..*/.#ifndef
5320: 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23 64 65   _SQLITE3_H_.#de
5330: 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f 48 5f  fine _SQLITE3_H_
5340: 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64 61 72  .#include <stdar
5350: 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65 65 64  g.h>     /* Need
5360: 65 64 20 66 6f 72 20 74 68 65 20 64 65 66 69 6e  ed for the defin
5370: 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69 73 74  ition of va_list
5380: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65 20   */../*.** Make 
5390: 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c 6c  sure we can call
53a0: 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f 6d   this stuff from
53b0: 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30 0a 65   C++..*/.#if 0.e
53c0: 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64  xtern "C" {.#end
53d0: 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64 20 74  if.../*.** Add t
53e0: 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20 6f 76  he ability to ov
53f0: 65 72 72 69 64 65 20 27 65 78 74 65 72 6e 27 0a  erride 'extern'.
5400: 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
5410: 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66 69 6e  E_EXTERN.# defin
5420: 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20  e SQLITE_EXTERN 
5430: 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a 0a 23  extern.#endif..#
5440: 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 41 50  ifndef SQLITE_AP
5450: 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  I.# define SQLIT
5460: 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a 0a 2f  E_API.#endif.../
5470: 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d 6f 70  *.** These no-op
5480: 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65 64   macros are used
5490: 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69 6e 74   in front of int
54a0: 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72 6b 20  erfaces to mark 
54b0: 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  those.** interfa
54c0: 63 65 73 20 61 73 20 65 69 74 68 65 72 20 64 65  ces as either de
54d0: 70 72 65 63 61 74 65 64 20 6f 72 20 65 78 70 65  precated or expe
54e0: 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77 20 61  rimental.  New a
54f0: 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73  pplications.** s
5500: 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20 64 65  hould not use de
5510: 70 72 65 63 61 74 65 64 20 69 6e 74 65 72 66 61  precated interfa
5520: 63 65 73 20 2d 20 74 68 65 79 20 61 72 65 20 73  ces - they are s
5530: 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63 6b 77  upport for backw
5540: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
5550: 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41 70 70  ility only.  App
5560: 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65 72 73  lication writers
5570: 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61 72 65   should be aware
5580: 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72 69 6d   that.** experim
5590: 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ental interfaces
55a0: 20 61 72 65 20 73 75 62 6a 65 63 74 20 74 6f 20   are subject to 
55b0: 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e 74 20  change in point 
55c0: 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  releases..**.** 
55d0: 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75 73 65  These macros use
55e0: 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74 6f 20  d to resolve to 
55f0: 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20 6f 66  various kinds of
5600: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
5610: 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20 67 65  that.** would ge
5620: 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67 20 6d  nerate warning m
5630: 65 73 73 61 67 65 73 20 77 68 65 6e 20 74 68 65  essages when the
5640: 79 20 77 65 72 65 20 75 73 65 64 2e 20 20 42 75  y were used.  Bu
5650: 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70 69 6c  t that.** compil
5660: 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64 20 75  er magic ended u
5670: 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73 75 63  p generating suc
5680: 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20 62 75  h a flurry of bu
5690: 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74 68 61  g reports.** tha
56a0: 74 20 77 65 20 68 61 76 65 20 74 61 6b 65 6e 20  t we have taken 
56b0: 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64 20 67  it all out and g
56c0: 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73 69 6e  one back to usin
56d0: 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f 6f 70  g simple.** noop
56e0: 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64 65 66   macros..*/.#def
56f0: 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50 52 45  ine SQLITE_DEPRE
5700: 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20 53 51  CATED.#define SQ
5710: 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41  LITE_EXPERIMENTA
5720: 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72 65 20  L../*.** Ensure 
5730: 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20 77 65  these symbols we
5740: 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64 20 62  re not defined b
5750: 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75 73 20  y some previous 
5760: 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a 2f 0a  header file..*/.
5770: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 56 45  #ifdef SQLITE_VE
5780: 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20 53 51  RSION.# undef SQ
5790: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 65 6e  LITE_VERSION.#en
57a0: 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c 49 54  dif.#ifdef SQLIT
57b0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
57c0: 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
57d0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 0a 23  VERSION_NUMBER.#
57e0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
57f0: 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
5800: 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65 72 73  ime Library Vers
5810: 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 0a 2a  ion Numbers.**.*
5820: 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f  * ^(The [SQLITE_
5830: 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65 70 72  VERSION] C prepr
5840: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 6e  ocessor macro in
5850: 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68 20 68   the sqlite3.h h
5860: 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75 61 74  eader.** evaluat
5870: 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6c  es to a string l
5880: 69 74 65 72 61 6c 20 74 68 61 74 20 69 73 20 74  iteral that is t
5890: 68 65 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  he SQLite versio
58a0: 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f 72 6d  n in the.** form
58b0: 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65 72 65  at "X.Y.Z" where
58c0: 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f 72 20   X is the major 
58d0: 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28  version number (
58e0: 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a 2a 20  always 3 for.** 
58f0: 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59 20 69  SQLite3) and Y i
5900: 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65 72 73  s the minor vers
5910: 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64 20 5a  ion number and Z
5920: 20 69 73 20 74 68 65 20 72 65 6c 65 61 73 65 20   is the release 
5930: 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e 28 54  number.)^.** ^(T
5940: 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49  he [SQLITE_VERSI
5950: 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70 72 65  ON_NUMBER] C pre
5960: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
5970: 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e 20 69  resolves to an i
5980: 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68 20 74  nteger.** with t
5990: 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30 30 30  he value (X*1000
59a0: 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b 20 5a  000 + Y*1000 + Z
59b0: 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20 61 6e  ) where X, Y, an
59c0: 64 20 5a 20 61 72 65 20 74 68 65 20 73 61 6d 65  d Z are the same
59d0: 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73 65 64  .** numbers used
59e0: 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   in [SQLITE_VERS
59f0: 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65 20 53  ION].)^.** The S
5a00: 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55  QLITE_VERSION_NU
5a10: 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67 69 76  MBER for any giv
5a20: 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  en release of SQ
5a30: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a  Lite will also.*
5a40: 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68 61 6e  * be larger than
5a50: 20 74 68 65 20 72 65 6c 65 61 73 65 20 66 72 6f   the release fro
5a60: 6d 20 77 68 69 63 68 20 69 74 20 69 73 20 64 65  m which it is de
5a70: 72 69 76 65 64 2e 20 20 45 69 74 68 65 72 20 59  rived.  Either Y
5a80: 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65 6c 64   will.** be held
5a90: 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20 5a 20   constant and Z 
5aa0: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e  will be incremen
5ab0: 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20 77 69  ted or else Y wi
5ac0: 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e 74 65  ll be incremente
5ad0: 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c 6c 20  d.** and Z will 
5ae0: 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65 72 6f  be reset to zero
5af0: 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20 76 65  ..**.** Since ve
5b00: 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20 53 51  rsion 3.6.18, SQ
5b10: 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f 64 65  Lite source code
5b20: 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72 65 64   has been stored
5b30: 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72   in the.** <a hr
5b40: 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 66  ef="http://www.f
5b50: 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f 22 3e  ossil-scm.org/">
5b60: 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75 72 61  Fossil configura
5b70: 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 0a  tion management.
5b80: 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e 20 20  ** system</a>.  
5b90: 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f 55 52  ^The SQLITE_SOUR
5ba0: 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76 61 6c  CE_ID macro eval
5bb0: 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20 73 74  uates to.** a st
5bc0: 72 69 6e 67 20 77 68 69 63 68 20 69 64 65 6e 74  ring which ident
5bd0: 69 66 69 65 73 20 61 20 70 61 72 74 69 63 75 6c  ifies a particul
5be0: 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66 20 53  ar check-in of S
5bf0: 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69 6e 20  QLite.** within 
5c00: 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  its configuratio
5c10: 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73 79 73  n management sys
5c20: 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c 49 54  tem.  ^The SQLIT
5c30: 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a 20 73  E_SOURCE_ID.** s
5c40: 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73 20 74  tring contains t
5c50: 68 65 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65  he date and time
5c60: 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d 69 6e   of the check-in
5c70: 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20 53 48   (UTC) and an SH
5c80: 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20 74 68  A1.** hash of th
5c90: 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63 65 20  e entire source 
5ca0: 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  tree..**.** See 
5cb0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 6c  also: [sqlite3_l
5cc0: 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a 2a 2a  ibversion()],.**
5cd0: 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   [sqlite3_libver
5ce0: 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d 2c 20  sion_number()], 
5cf0: 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  [sqlite3_sourcei
5d00: 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
5d10: 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20  _version()] and 
5d20: 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69  [sqlite_source_i
5d30: 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  d()]..*/.#define
5d40: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 20   SQLITE_VERSION 
5d50: 20 20 20 20 20 20 20 22 33 2e 37 2e 31 34 22 0a         "3.7.14".
5d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
5d70: 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 33 30  ERSION_NUMBER 30
5d80: 30 37 30 31 34 0a 23 64 65 66 69 6e 65 20 53 51  07014.#define SQ
5d90: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
5da0: 20 20 20 20 22 32 30 31 32 2d 30 38 2d 32 34 20      "2012-08-24 
5db0: 30 31 3a 30 37 3a 35 32 20 64 34 63 64 36 30 31  01:07:52 d4cd601
5dc0: 37 63 39 38 37 35 39 34 37 61 30 35 62 31 64 63  7c9875947a05b1dc
5dd0: 33 36 35 33 38 64 34 32 37 32 66 62 31 38 37 33  36538d4272fb1873
5de0: 39 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  9"../*.** CAPI3R
5df0: 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62  EF: Run-Time Lib
5e00: 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d  rary Version Num
5e10: 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  bers.** KEYWORDS
5e20: 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f  : sqlite3_versio
5e30: 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  n, sqlite3_sourc
5e40: 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  eid.**.** These 
5e50: 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f 76 69  interfaces provi
5e60: 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f  de the same info
5e70: 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65 20 5b  rmation as the [
5e80: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 2c  SQLITE_VERSION],
5e90: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
5ea0: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61 6e 64  ION_NUMBER], and
5eb0: 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f   [SQLITE_SOURCE_
5ec0: 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73  ID] C preprocess
5ed0: 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62 75 74  or macros.** but
5ee0: 20 61 72 65 20 61 73 73 6f 63 69 61 74 65 64 20   are associated 
5ef0: 77 69 74 68 20 74 68 65 20 6c 69 62 72 61 72 79  with the library
5f00: 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20   instead of the 
5f10: 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20 5e 28  header file.  ^(
5f20: 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72 6f 67  Cautious.** prog
5f30: 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 69 6e  rammers might in
5f40: 63 6c 75 64 65 20 61 73 73 65 72 74 28 29 20 73  clude assert() s
5f50: 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68 65  tatements in the
5f60: 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ir application t
5f70: 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68 61 74  o.** verify that
5f80: 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
5f90: 20 62 79 20 74 68 65 73 65 20 69 6e 74 65 72 66   by these interf
5fa0: 61 63 65 73 20 6d 61 74 63 68 20 74 68 65 20 6d  aces match the m
5fb0: 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68 65 20  acros in.** the 
5fc0: 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68 75 73  header, and thus
5fd0: 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   insure that the
5fe0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 0a   application is.
5ff0: 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
6000: 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72 61 72   matching librar
6010: 79 20 61 6e 64 20 68 65 61 64 65 72 20 66 69 6c  y and header fil
6020: 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  es..**.** <block
6030: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 61  quote><pre>.** a
6040: 73 73 65 72 74 28 20 73 71 6c 69 74 65 33 5f 6c  ssert( sqlite3_l
6050: 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72  ibversion_number
6060: 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52 53 49  ()==SQLITE_VERSI
6070: 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a 2a 20  ON_NUMBER );.** 
6080: 61 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73  assert( strcmp(s
6090: 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28  qlite3_sourceid(
60a0: 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  ),SQLITE_SOURCE_
60b0: 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61 73 73  ID)==0 );.** ass
60c0: 65 72 74 28 20 73 74 72 63 6d 70 28 73 71 6c 69  ert( strcmp(sqli
60d0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
60e0: 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 29  ,SQLITE_VERSION)
60f0: 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  ==0 );.** </pre>
6100: 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
6110: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
6120: 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72  e3_version[] str
6130: 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63 6f 6e  ing constant con
6140: 74 61 69 6e 73 20 74 68 65 20 74 65 78 74 20 6f  tains the text o
6150: 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  f [SQLITE_VERSIO
6160: 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20 5e 54  N].** macro.  ^T
6170: 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65  he sqlite3_libve
6180: 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69 6f 6e  rsion() function
6190: 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
61a0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74 6f 20  er to the.** to 
61b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65 72 73  the sqlite3_vers
61c0: 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63 6f 6e  ion[] string con
61d0: 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71 6c 69  stant.  The sqli
61e0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29  te3_libversion()
61f0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
6200: 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75 73 65  provided for use
6210: 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65 20 44   in DLLs since D
6220: 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c 6c 79  LL users usually
6230: 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a 2a 20   do not have.** 
6240: 64 69 72 65 63 74 20 61 63 63 65 73 73 20 74 6f  direct access to
6250: 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74   string constant
6260: 73 20 77 69 74 68 69 6e 20 74 68 65 20 44 4c 4c  s within the DLL
6270: 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
6280: 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75  e3_libversion_nu
6290: 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f 6e 20  mber() function 
62a0: 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67  returns an integ
62b0: 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a 20 5b  er equal to.** [
62c0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
62d0: 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20 73 71  UMBER].  ^The sq
62e0: 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64 28 29  lite3_sourceid()
62f0: 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
6300: 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  s .** a pointer 
6310: 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f 6e 73  to a string cons
6320: 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c 75 65  tant whose value
6330: 20 69 73 20 74 68 65 20 73 61 6d 65 20 61 73 20   is the same as 
6340: 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  the .** [SQLITE_
6350: 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65  SOURCE_ID] C pre
6360: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 2e  processor macro.
6370: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
6380: 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e   [sqlite_version
6390: 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f  ()] and [sqlite_
63a0: 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f  source_id()]..*/
63b0: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
63c0: 74 20 63 68 61 72 20 73 71 6c 69 74 65 33 5f 76  t char sqlite3_v
63d0: 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c 49 54  ersion[] = SQLIT
63e0: 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c 49 54  E_VERSION;.SQLIT
63f0: 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
6400: 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72   *sqlite3_libver
6410: 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49  sion(void);.SQLI
6420: 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61  TE_API const cha
6430: 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  r *sqlite3_sourc
6440: 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  eid(void);.SQLIT
6450: 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
6460: 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d  3_libversion_num
6470: 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  ber(void);../*.*
6480: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
6490: 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43 6f 6d  Time Library Com
64a0: 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  pilation Options
64b0: 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a 2a 0a   Diagnostics.**.
64c0: 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
64d0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
64e0: 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65  ed() function re
64f0: 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a 2a 2a  turns 0 or 1 .**
6500: 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68 65 74   indicating whet
6510: 68 65 72 20 74 68 65 20 73 70 65 63 69 66 69 65  her the specifie
6520: 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64 65 66  d option was def
6530: 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f 6d 70  ined at .** comp
6540: 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  ile time.  ^The 
6550: 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78 20 6d  SQLITE_ prefix m
6560: 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20 66 72  ay be omitted fr
6570: 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74 69 6f  om the .** optio
6580: 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20 74 6f  n name passed to
6590: 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65   sqlite3_compile
65a0: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e 20 20  option_used().  
65b0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
65c0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
65d0: 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  n_get() function
65e0: 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74 69 6e   allows iteratin
65f0: 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20 6c 69  g.** over the li
6600: 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20 74 68  st of options th
6610: 61 74 20 77 65 72 65 20 64 65 66 69 6e 65 64 20  at were defined 
6620: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 20  at compile time 
6630: 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e 67 20  by.** returning 
6640: 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69 6c 65  the N-th compile
6650: 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73 74 72   time option str
6660: 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73 20 6f  ing.  ^If N is o
6670: 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a 2a 20  ut of range,.** 
6680: 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f  sqlite3_compileo
6690: 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65 74 75  ption_get() retu
66a0: 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
66b0: 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49 54 45  er.  ^The SQLITE
66c0: 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69 73 20  _ .** prefix is 
66d0: 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61 6e 79  omitted from any
66e0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
66f0: 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74 65 33  d by .** sqlite3
6700: 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67  _compileoption_g
6710: 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53 75 70  et()..**.** ^Sup
6720: 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64 69 61  port for the dia
6730: 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69 6f 6e  gnostic function
6740: 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  s sqlite3_compil
6750: 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 0a 2a  eoption_used().*
6760: 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
6770: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
6780: 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64  ) may be omitted
6790: 20 62 79 20 73 70 65 63 69 66 79 69 6e 67 20 74   by specifying t
67a0: 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  he .** [SQLITE_O
67b0: 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54 49 4f  MIT_COMPILEOPTIO
67c0: 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f 6e 20  N_DIAGS] option 
67d0: 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
67e0: 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
67f0: 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 5b   SQL functions [
6800: 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65 6f 70  sqlite_compileop
6810: 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61 6e 64  tion_used()] and
6820: 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70  .** [sqlite_comp
6830: 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 5d  ileoption_get()]
6840: 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70 69 6c   and the [compil
6850: 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67 6d 61  e_options pragma
6860: 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51  ]..*/.#ifndef SQ
6870: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
6880: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a 53 51  EOPTION_DIAGS.SQ
6890: 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
68a0: 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69  ite3_compileopti
68b0: 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20 63 68  on_used(const ch
68c0: 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b 0a 53  ar *zOptName);.S
68d0: 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
68e0: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
68f0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
6900: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
6910: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
6920: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
6930: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
6940: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
6950: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
6960: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
6970: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
6980: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
6990: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
69a0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
69b0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
69c0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
69d0: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
69e0: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
69f0: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
6a00: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
6a10: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
6a20: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
6a30: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
6a40: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
6a50: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
6a60: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
6a70: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
6a80: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
6a90: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
6aa0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
6ab0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
6ac0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
6ad0: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
6ae0: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
6af0: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
6b00: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
6b10: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
6b20: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
6b30: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
6b40: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
6b50: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
6b60: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
6b70: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
6b80: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
6b90: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
6ba0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
6bb0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
6bc0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
6bd0: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
6be0: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
6bf0: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
6c00: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
6c10: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
6c20: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
6c30: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
6c40: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
6c50: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
6c60: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
6c70: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
6c80: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
6c90: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
6ca0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
6cb0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
6cc0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
6cd0: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
6ce0: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
6cf0: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
6d00: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
6d10: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
6d20: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
6d30: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
6d40: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
6d50: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
6d60: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
6d70: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
6d80: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
6d90: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
6da0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
6db0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
6dc0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
6dd0: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
6de0: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
6df0: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
6e00: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
6e10: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
6e20: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
6e30: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
6e40: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
6e50: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
6e60: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
6e70: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
6e80: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
6e90: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
6ea0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
6eb0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
6ec0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
6ed0: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
6ee0: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
6ef0: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
6f00: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
6f10: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
6f20: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
6f30: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
6f40: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
6f50: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
6f60: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
6f70: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
6f80: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
6f90: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
6fa0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
6fb0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
6fc0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
6fd0: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
6fe0: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
6ff0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
7000: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
7010: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
7020: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
7030: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
7040: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
7050: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
7060: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
7070: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
7080: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7090: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
70a0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
70b0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
70c0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
70d0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
70e0: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
70f0: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
7100: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
7110: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
7120: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
7130: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
7140: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
7150: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
7160: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
7170: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
7180: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
7190: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
71a0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
71b0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
71c0: 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  se()].** and [sq
71d0: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
71e0: 5d 20 61 72 65 20 69 74 73 20 64 65 73 74 72 75  ] are its destru
71f0: 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20 61 72  ctors.  There ar
7200: 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  e many other.** 
7210: 69 6e 74 65 72 66 61 63 65 73 20 28 73 75 63 68  interfaces (such
7220: 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   as.** [sqlite3_
7230: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b  prepare_v2()], [
7240: 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
7250: 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e 64 0a  unction()], and.
7260: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79  ** [sqlite3_busy
7270: 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f 20 6e  _timeout()] to n
7280: 61 6d 65 20 62 75 74 20 74 68 72 65 65 29 20 74  ame but three) t
7290: 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64 73 20  hat are methods 
72a0: 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65 33  on an.** sqlite3
72b0: 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79 70 65   object..*/.type
72c0: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
72d0: 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f 2a 0a  e3 sqlite3;../*.
72e0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36 34 2d  ** CAPI3REF: 64-
72f0: 42 69 74 20 49 6e 74 65 67 65 72 20 54 79 70 65  Bit Integer Type
7300: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  s.** KEYWORDS: s
7310: 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71 6c 69  qlite_int64 sqli
7320: 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a 2a 20  te_uint64.**.** 
7330: 42 65 63 61 75 73 65 20 74 68 65 72 65 20 69 73  Because there is
7340: 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74 66 6f   no cross-platfo
7350: 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63 69 66  rm way to specif
7360: 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  y 64-bit integer
7370: 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69 74 65   types.** SQLite
7380: 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65 64 65   includes typede
7390: 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20 73 69  fs for 64-bit si
73a0: 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67 6e 65  gned and unsigne
73b0: 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a 0a 2a  d integers..**.*
73c0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  * The sqlite3_in
73d0: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t64 and sqlite3_
73e0: 75 69 6e 74 36 34 20 61 72 65 20 74 68 65 20 70  uint64 are the p
73f0: 72 65 66 65 72 72 65 64 20 74 79 70 65 20 64 65  referred type de
7400: 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20 54 68  finitions..** Th
7410: 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 61  e sqlite_int64 a
7420: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
7430: 20 74 79 70 65 73 20 61 72 65 20 73 75 70 70 6f   types are suppo
7440: 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72  rted for backwar
7450: 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  ds.** compatibil
7460: 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ity only..**.** 
7470: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74  ^The sqlite3_int
7480: 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 69 6e  64 and sqlite_in
7490: 74 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74  t64 types can st
74a0: 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ore integer valu
74b0: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 2d 39  es.** between -9
74c0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
74d0: 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37 32 30  08 and +92233720
74e0: 33 36 38 35 34 37 37 35 38 30 37 20 69 6e 63 6c  36854775807 incl
74f0: 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  usive.  ^The.** 
7500: 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61  sqlite3_uint64 a
7510: 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  nd sqlite_uint64
7520: 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f 72 65   types can store
7530: 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20   integer values 
7540: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20 61 6e  .** between 0 an
7550: 64 20 2b 31 38 34 34 36 37 34 34 30 37 33 37 30  d +1844674407370
7560: 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73 69 76  9551615 inclusiv
7570: 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51 4c  e..*/.#ifdef SQL
7580: 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 0a 20  ITE_INT64_TYPE. 
7590: 20 74 79 70 65 64 65 66 20 53 51 4c 49 54 45 5f   typedef SQLITE_
75a0: 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c 69 74  INT64_TYPE sqlit
75b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
75c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51 4c 49  ef unsigned SQLI
75d0: 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71  TE_INT64_TYPE sq
75e0: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
75f0: 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53 43 5f  if defined(_MSC_
7600: 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65 64 28  VER) || defined(
7610: 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a 20 20  __BORLANDC__).  
7620: 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36 34 20  typedef __int64 
7630: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
7640: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
7650: 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f   __int64 sqlite_
7660: 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a 20 20  uint64;.#else.  
7670: 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c 6f 6e  typedef long lon
7680: 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69 6e 74  g int sqlite_int
7690: 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e  64;.  typedef un
76a0: 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f 6e 67  signed long long
76b0: 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69 6e 74   int sqlite_uint
76c0: 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70 65 64  64;.#endif.typed
76d0: 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20  ef sqlite_int64 
76e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b 0a 74  sqlite3_int64;.t
76f0: 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 75 69  ypedef sqlite_ui
7700: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 69 6e  nt64 sqlite3_uin
7710: 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66 20 63  t64;../*.** If c
7720: 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61 20 70  ompiling for a p
7730: 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20 6c 61  rocessor that la
7740: 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  cks floating poi
7750: 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a 20 73  nt support,.** s
7760: 75 62 73 74 69 74 75 74 65 20 69 6e 74 65 67 65  ubstitute intege
7770: 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67 2d 70  r for floating-p
7780: 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65 66 20  oint..*/.#ifdef 
7790: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c 4f 41  SQLITE_OMIT_FLOA
77a0: 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64 65 66  TING_POINT.# def
77b0: 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c 69 74  ine double sqlit
77c0: 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69 66 0a  e3_int64.#endif.
77d0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
77e0: 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74 61 62   Closing A Datab
77f0: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase Connection.*
7800: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
7810: 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71  3_close() and sq
7820: 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29  lite3_close_v2()
7830: 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
7840: 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66 6f 72  structors.** for
7850: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
7860: 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73  bject..** ^Calls
7870: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   to sqlite3_clos
7880: 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
7890: 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74 75 72  close_v2() retur
78a0: 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 0a 2a  n SQLITE_OK if.*
78b0: 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20  * the [sqlite3] 
78c0: 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63 65 73  object is succes
78d0: 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79 65 64  sfully destroyed
78e0: 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63 69 61   and all associa
78f0: 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 73  ted.** resources
7900: 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64   are deallocated
7910: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
7920: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7930: 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61 74 65  ion is associate
7940: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
7950: 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73  ed prepared.** s
7960: 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75 6e 66  tatements or unf
7970: 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f  inished sqlite3_
7980: 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73 20 74  backup objects t
7990: 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  hen sqlite3_clos
79a0: 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65 61 76  e().** will leav
79b0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
79c0: 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 20 61  onnection open a
79d0: 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  nd return [SQLIT
79e0: 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49 66 20  E_BUSY]..** ^If 
79f0: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
7a00: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74  () is called wit
7a10: 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20 70 72  h unfinalized pr
7a20: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
7a30: 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69 6e 69 73  s.** and unfinis
7a40: 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61 63 6b  hed sqlite3_back
7a50: 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ups, then the da
7a60: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
7a70: 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61 6e 20  n becomes.** an 
7a80: 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62 69 65  unusable "zombie
7a90: 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61 75 74  " which will aut
7aa0: 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20 64 65  omatically be de
7ab0: 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e 20 74  allocated when t
7ac0: 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65 70 61  he.** last prepa
7ad0: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 69 73  red statement is
7ae0: 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20 74 68   finalized or th
7af0: 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 62  e last sqlite3_b
7b00: 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69 6e 69  ackup is.** fini
7b10: 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c 69 74  shed.  The sqlit
7b20: 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69 6e  e3_close_v2() in
7b30: 74 65 72 66 61 63 65 20 69 73 20 69 6e 74 65 6e  terface is inten
7b40: 64 65 64 20 66 6f 72 20 75 73 65 20 77 69 74 68  ded for use with
7b50: 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75 61 67  .** host languag
7b60: 65 73 20 74 68 61 74 20 61 72 65 20 67 61 72 62  es that are garb
7b70: 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c 20 61  age collected, a
7b80: 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f 72 64  nd where the ord
7b90: 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 64  er in which.** d
7ba0: 65 73 74 72 75 63 74 6f 72 73 20 61 72 65 20 63  estructors are c
7bb0: 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74 72 61  alled is arbitra
7bc0: 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ry..**.** Applic
7bd0: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 5b 73  ations should [s
7be0: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
7bf0: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
7c00: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
7c10: 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  ents],.** [sqlit
7c20: 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20  e3_blob_close | 
7c30: 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42  close] all [BLOB
7c40: 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 20 0a   handles], and .
7c50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
7c60: 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69 6e 69  up_finish | fini
7c70: 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74 65 33  sh] all [sqlite3
7c80: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
7c90: 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
7ca0: 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ith the [sqlite3
7cb0: 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72 20 74  ] object prior t
7cc0: 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74 6f 20  o attempting to 
7cd0: 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65 63 74  close the object
7ce0: 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69 74 65  .  ^If.** sqlite
7cf0: 33 5f 63 6c 6f 73 65 28 29 20 69 73 20 63 61 6c  3_close() is cal
7d00: 6c 65 64 20 6f 6e 20 61 20 5b 64 61 74 61 62 61  led on a [databa
7d10: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
7d20: 68 61 74 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a  hat still has.**
7d30: 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 5b 70 72   outstanding [pr
7d40: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
7d50: 73 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65  s], [BLOB handle
7d60: 73 5d 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73  s], and/or.** [s
7d70: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f  qlite3_backup] o
7d80: 62 6a 65 63 74 73 20 74 68 65 6e 20 69 74 20 72  bjects then it r
7d90: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4f 4b  eturns SQLITE_OK
7da0: 20 62 75 74 20 74 68 65 20 64 65 61 6c 6c 6f 63   but the dealloc
7db0: 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f  ation.** of reso
7dc0: 75 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65  urces is deferre
7dd0: 64 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65  d until all [pre
7de0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
7df0: 5d 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73  ], [BLOB handles
7e00: 5d 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  ],.** and [sqlit
7e10: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
7e20: 74 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74  ts are also dest
7e30: 72 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  royed..**.** ^If
7e40: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62   an [sqlite3] ob
7e50: 6a 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65  ject is destroye
7e60: 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61  d while a transa
7e70: 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a  ction is open,.*
7e80: 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f  * the transactio
7e90: 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  n is automatical
7ea0: 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
7eb0: 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61  **.** The C para
7ec0: 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
7ed0: 33 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20  3_close(C)] and 
7ee0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76  [sqlite3_close_v
7ef0: 32 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  2(C)].** must be
7f00: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a   either a NULL.*
7f10: 2a 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20  * pointer or an 
7f20: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
7f30: 20 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65   pointer obtaine
7f40: 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74  d.** from [sqlit
7f50: 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c  e3_open()], [sql
7f60: 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20  ite3_open16()], 
7f70: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f  or.** [sqlite3_o
7f80: 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e  pen_v2()], and n
7f90: 6f 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c  ot previously cl
7fa0: 6f 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  osed..** ^Callin
7fb0: 67 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  g sqlite3_close(
7fc0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f  ) or sqlite3_clo
7fd0: 73 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e  se_v2() with a N
7fe0: 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61  ULL pointer.** a
7ff0: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72  rgument is a har
8000: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
8010: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
8020: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c  qlite3_close(sql
8030: 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
8040: 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
8050: 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65 33 2a  lose_v2(sqlite3*
8060: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
8070: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
8080: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
8090: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
80a0: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
80b0: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
80c0: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
80d0: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
80e0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
80f0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
8100: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
8110: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
8120: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
8130: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
8140: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
8150: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
8160: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
8170: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8180: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
8190: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
81a0: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
81b0: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
81c0: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
81d0: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
81e0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
81f0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
8200: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
8210: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
8220: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
8230: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
8240: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
8250: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
8260: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
8270: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
8280: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
8290: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
82a0: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
82b0: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
82c0: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
82d0: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
82e0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
82f0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
8300: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
8310: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
8320: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
8330: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
8340: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
8350: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
8360: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
8370: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
8380: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
8390: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
83a0: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
83b0: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
83c0: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
83d0: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
83e0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
83f0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
8400: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
8410: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
8420: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
8430: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
8440: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
8450: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
8460: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
8470: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
8480: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
8490: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
84a0: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
84b0: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
84c0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
84d0: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
84e0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
84f0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
8500: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
8510: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
8520: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
8530: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
8540: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
8550: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
8560: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
8570: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
8580: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
8590: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
85a0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
85b0: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
85c0: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
85d0: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
85e0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
85f0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
8600: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
8610: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
8620: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
8630: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
8640: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
8650: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
8660: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
8670: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
8680: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
8690: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
86a0: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
86b0: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
86c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
86d0: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
86e0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
86f0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
8700: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
8710: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
8720: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
8730: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
8740: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
8750: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
8760: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
8770: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
8780: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
8790: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
87a0: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
87b0: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
87c0: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
87d0: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
87e0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
87f0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
8800: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
8810: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
8820: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
8830: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
8840: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
8850: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
8860: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
8870: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
8880: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
8890: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
88a0: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
88b0: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
88c0: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
88d0: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
88e0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
88f0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
8900: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
8910: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
8920: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
8930: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
8940: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
8950: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
8960: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
8970: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
8980: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
8990: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
89a0: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
89b0: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
89c0: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
89d0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
89e0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
89f0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
8a00: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
8a10: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
8a20: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
8a30: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
8a40: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
8a50: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
8a60: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
8a70: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
8a80: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
8a90: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
8aa0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
8ab0: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
8ac0: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
8ad0: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
8ae0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
8af0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
8b00: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
8b10: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
8b20: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
8b30: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
8b40: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
8b50: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
8b60: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
8b70: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
8b80: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
8b90: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
8ba0: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
8bb0: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
8bc0: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
8bd0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
8be0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
8bf0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
8c00: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
8c10: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
8c20: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
8c30: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
8c40: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8c50: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
8c60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
8c70: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74  t not close [dat
8c80: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
8c90: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
8ca0: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
8cb0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
8cc0: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
8cd0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8ce0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
8cf0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
8d00: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
8d10: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
8d20: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
8d30: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
8d40: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
8d50: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
8d60: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
8d70: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
8d80: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
8d90: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
8da0: 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73  qlite3_exec(.  s
8db0: 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20  qlite3*,        
8dc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8dd0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
8de0: 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
8df0: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  .  const char *s
8e00: 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  ql,             
8e10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
8e20: 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
8e30: 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  ated */.  int (*
8e40: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
8e50: 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a  int,char**,char*
8e60: 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b  *),  /* Callback
8e70: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
8e80: 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20  oid *,          
8e90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8ea0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74            /* 1st
8eb0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c   argument to cal
8ec0: 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20  lback */.  char 
8ed0: 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20  **errmsg        
8ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8ef0: 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d        /* Error m
8f00: 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20  sg written here 
8f10: 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
8f20: 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f  I3REF: Result Co
8f30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
8f40: 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65 72 72 6f   SQLITE_OK {erro
8f50: 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f 72 20 63  r code} {error c
8f60: 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  odes}.** KEYWORD
8f70: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 7d  S: {result code}
8f80: 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 73 7d 0a   {result codes}.
8f90: 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74  **.** Many SQLit
8fa0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
8fb0: 72 6e 20 61 6e 20 69 6e 74 65 67 65 72 20 72 65  rn an integer re
8fc0: 73 75 6c 74 20 63 6f 64 65 20 66 72 6f 6d 20 74  sult code from t
8fd0: 68 65 20 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20  he set shown.** 
8fe0: 68 65 72 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  here in order to
8ff0: 20 69 6e 64 69 63 61 74 65 20 73 75 63 63 65 73   indicate succes
9000: 73 20 6f 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a  s or failure..**
9010: 0a 2a 2a 20 4e 65 77 20 65 72 72 6f 72 20 63 6f  .** New error co
9020: 64 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  des may be added
9030: 20 69 6e 20 66 75 74 75 72 65 20 76 65 72 73 69   in future versi
9040: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ons of SQLite..*
9050: 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
9060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41  SQLITE_IOERR_REA
9070: 44 20 7c 20 65 78 74 65 6e 64 65 64 20 72 65 73  D | extended res
9080: 75 6c 74 20 63 6f 64 65 73 5d 2c 0a 2a 2a 20 5b  ult codes],.** [
9090: 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f  sqlite3_vtab_on_
90a0: 63 6f 6e 66 6c 69 63 74 28 29 5d 20 5b 53 51 4c  conflict()] [SQL
90b0: 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
90c0: 65 73 75 6c 74 20 63 6f 64 65 73 5d 2e 0a 2a 2f  esult codes]..*/
90d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
90e0: 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20 20  OK           0  
90f0: 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72   /* Successful r
9100: 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69  esult */./* begi
9110: 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63  nning-of-error-c
9120: 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20  odes */.#define 
9130: 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20  SQLITE_ERROR    
9140: 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65      1   /* SQL e
9150: 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20  rror or missing 
9160: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
9170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
9180: 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49  NAL     2   /* I
9190: 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72  nternal logic er
91a0: 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f  ror in SQLite */
91b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
91c0: 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20 20  PERM         3  
91d0: 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69   /* Access permi
91e0: 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a  ssion denied */.
91f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
9200: 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20 20  BORT        4   
9210: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74  /* Callback rout
9220: 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61 6e  ine requested an
9230: 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e   abort */.#defin
9240: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20  e SQLITE_BUSY   
9250: 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65        5   /* The
9260: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
9270: 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66  s locked */.#def
9280: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
9290: 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41  D       6   /* A
92a0: 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61   table in the da
92b0: 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64  tabase is locked
92c0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
92d0: 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20  TE_NOMEM        
92e0: 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28  7   /* A malloc(
92f0: 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66  ) failed */.#def
9300: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
9310: 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41  NLY     8   /* A
9320: 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20  ttempt to write 
9330: 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62  a readonly datab
9340: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
9350: 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20  QLITE_INTERRUPT 
9360: 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74     9   /* Operat
9370: 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62  ion terminated b
9380: 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  y sqlite3_interr
9390: 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20  upt()*/.#define 
93a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20  SQLITE_IOERR    
93b0: 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20     10   /* Some 
93c0: 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f  kind of disk I/O
93d0: 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20   error occurred 
93e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
93f0: 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31 31  E_CORRUPT     11
9400: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
9410: 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73  se disk image is
9420: 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64   malformed */.#d
9430: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54  efine SQLITE_NOT
9440: 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a  FOUND    12   /*
9450: 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20   Unknown opcode 
9460: 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  in sqlite3_file_
9470: 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65  control() */.#de
9480: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c  fine SQLITE_FULL
9490: 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20          13   /* 
94a0: 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64  Insertion failed
94b0: 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61 73   because databas
94c0: 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65  e is full */.#de
94d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54  fine SQLITE_CANT
94e0: 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20  OPEN    14   /* 
94f0: 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74  Unable to open t
9500: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9510: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
9520: 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31  TE_PROTOCOL    1
9530: 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  5   /* Database 
9540: 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72  lock protocol er
9550: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
9560: 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20  QLITE_EMPTY     
9570: 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61    16   /* Databa
9580: 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23  se is empty */.#
9590: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43  define SQLITE_SC
95a0: 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f  HEMA      17   /
95b0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 73  * The database s
95c0: 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f  chema changed */
95d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
95e0: 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20 20  TOOBIG      18  
95f0: 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c   /* String or BL
9600: 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65 20  OB exceeds size 
9610: 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65  limit */.#define
9620: 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49   SQLITE_CONSTRAI
9630: 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72  NT  19   /* Abor
9640: 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61  t due to constra
9650: 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f  int violation */
9660: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9670: 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20 20  MISMATCH    20  
9680: 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69   /* Data type mi
9690: 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e  smatch */.#defin
96a0: 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  e SQLITE_MISUSE 
96b0: 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62       21   /* Lib
96c0: 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72  rary used incorr
96d0: 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65  ectly */.#define
96e0: 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20   SQLITE_NOLFS   
96f0: 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73      22   /* Uses
9700: 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74   OS features not
9710: 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f   supported on ho
9720: 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  st */.#define SQ
9730: 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20 20  LITE_AUTH       
9740: 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69   23   /* Authori
9750: 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  zation denied */
9760: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9770: 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20 20  FORMAT      24  
9780: 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61   /* Auxiliary da
9790: 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72  tabase format er
97a0: 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
97b0: 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20  QLITE_RANGE     
97c0: 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61    25   /* 2nd pa
97d0: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
97e0: 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72  e3_bind out of r
97f0: 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ange */.#define 
9800: 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20  SQLITE_NOTADB   
9810: 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20     26   /* File 
9820: 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e  opened that is n
9830: 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
9840: 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  le */.#define SQ
9850: 4c 49 54 45 5f 52 4f 57 20 20 20 20 20 20 20 20  LITE_ROW        
9860: 20 31 30 30 20 20 2f 2a 20 73 71 6c 69 74 65 33   100  /* sqlite3
9870: 5f 73 74 65 70 28 29 20 68 61 73 20 61 6e 6f 74  _step() has anot
9880: 68 65 72 20 72 6f 77 20 72 65 61 64 79 20 2a 2f  her row ready */
9890: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
98a0: 44 4f 4e 45 20 20 20 20 20 20 20 20 31 30 31 20  DONE        101 
98b0: 20 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70   /* sqlite3_step
98c0: 28 29 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  () has finished 
98d0: 65 78 65 63 75 74 69 6e 67 20 2a 2f 0a 2f 2a 20  executing */./* 
98e0: 65 6e 64 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  end-of-error-cod
98f0: 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  es */../*.** CAP
9900: 49 33 52 45 46 3a 20 45 78 74 65 6e 64 65 64 20  I3REF: Extended 
9910: 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 20  Result Codes.** 
9920: 4b 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e  KEYWORDS: {exten
9930: 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 7d 20  ded error code} 
9940: 7b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  {extended error 
9950: 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52  codes}.** KEYWOR
9960: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
9970: 73 75 6c 74 20 63 6f 64 65 7d 20 7b 65 78 74 65  sult code} {exte
9980: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
9990: 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73 20  s}.**.** In its 
99a0: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
99b0: 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41 50  ation, SQLite AP
99c0: 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  I routines retur
99d0: 6e 20 6f 6e 65 20 6f 66 20 32 36 20 69 6e 74 65  n one of 26 inte
99e0: 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ger.** [SQLITE_O
99f0: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
9a00: 5d 2e 20 20 48 6f 77 65 76 65 72 2c 20 65 78 70  ].  However, exp
9a10: 65 72 69 65 6e 63 65 20 68 61 73 20 73 68 6f 77  erience has show
9a20: 6e 20 74 68 61 74 20 6d 61 6e 79 20 6f 66 0a 2a  n that many of.*
9a30: 2a 20 74 68 65 73 65 20 72 65 73 75 6c 74 20 63  * these result c
9a40: 6f 64 65 73 20 61 72 65 20 74 6f 6f 20 63 6f 61  odes are too coa
9a50: 72 73 65 2d 67 72 61 69 6e 65 64 2e 20 20 54 68  rse-grained.  Th
9a60: 65 79 20 64 6f 20 6e 6f 74 20 70 72 6f 76 69 64  ey do not provid
9a70: 65 20 61 73 0a 2a 2a 20 6d 75 63 68 20 69 6e 66  e as.** much inf
9a80: 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 70  ormation about p
9a90: 72 6f 62 6c 65 6d 73 20 61 73 20 70 72 6f 67 72  roblems as progr
9aa0: 61 6d 6d 65 72 73 20 6d 69 67 68 74 20 6c 69 6b  ammers might lik
9ab0: 65 2e 20 20 49 6e 20 61 6e 20 65 66 66 6f 72 74  e.  In an effort
9ac0: 20 74 6f 0a 2a 2a 20 61 64 64 72 65 73 73 20 74   to.** address t
9ad0: 68 69 73 2c 20 6e 65 77 65 72 20 76 65 72 73 69  his, newer versi
9ae0: 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 28 76  ons of SQLite (v
9af0: 65 72 73 69 6f 6e 20 33 2e 33 2e 38 20 61 6e 64  ersion 3.3.8 and
9b00: 20 6c 61 74 65 72 29 20 69 6e 63 6c 75 64 65 0a   later) include.
9b10: 2a 2a 20 73 75 70 70 6f 72 74 20 66 6f 72 20 61  ** support for a
9b20: 64 64 69 74 69 6f 6e 61 6c 20 72 65 73 75 6c 74  dditional result
9b30: 20 63 6f 64 65 73 20 74 68 61 74 20 70 72 6f 76   codes that prov
9b40: 69 64 65 20 6d 6f 72 65 20 64 65 74 61 69 6c 65  ide more detaile
9b50: 64 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  d information.**
9b60: 20 61 62 6f 75 74 20 65 72 72 6f 72 73 2e 20 54   about errors. T
9b70: 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  he extended resu
9b80: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 65 6e 61  lt codes are ena
9b90: 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64  bled or disabled
9ba0: 0a 2a 2a 20 6f 6e 20 61 20 70 65 72 20 64 61 74  .** on a per dat
9bb0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
9bc0: 20 62 61 73 69 73 20 75 73 69 6e 67 20 74 68 65   basis using the
9bd0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
9be0: 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
9bf0: 65 73 28 29 5d 20 41 50 49 2e 0a 2a 2a 0a 2a 2a  es()] API..**.**
9c00: 20 53 6f 6d 65 20 6f 66 20 74 68 65 20 61 76 61   Some of the ava
9c10: 69 6c 61 62 6c 65 20 65 78 74 65 6e 64 65 64 20  ilable extended 
9c20: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
9c30: 20 6c 69 73 74 65 64 20 68 65 72 65 2e 0a 2a 2a   listed here..**
9c40: 20 4f 6e 65 20 6d 61 79 20 65 78 70 65 63 74 20   One may expect 
9c50: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 65 78  the number of ex
9c60: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
9c70: 64 65 73 20 77 69 6c 6c 20 62 65 20 65 78 70 61  des will be expa
9c80: 6e 64 0a 2a 2a 20 6f 76 65 72 20 74 69 6d 65 2e  nd.** over time.
9c90: 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
9ca0: 75 73 65 73 20 65 78 74 65 6e 64 65 64 20 72 65  uses extended re
9cb0: 73 75 6c 74 20 63 6f 64 65 73 20 73 68 6f 75 6c  sult codes shoul
9cc0: 64 20 65 78 70 65 63 74 0a 2a 2a 20 74 6f 20 73  d expect.** to s
9cd0: 65 65 20 6e 65 77 20 72 65 73 75 6c 74 20 63 6f  ee new result co
9ce0: 64 65 73 20 69 6e 20 66 75 74 75 72 65 20 72 65  des in future re
9cf0: 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
9d00: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
9d10: 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20 63 6f 64  TE_OK result cod
9d20: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 62 65 20  e will never be 
9d30: 65 78 74 65 6e 64 65 64 2e 20 20 49 74 20 77 69  extended.  It wi
9d40: 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20  ll always.** be 
9d50: 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e 0a 2a 2f  exactly zero..*/
9d60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9d70: 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20 20  IOERR_READ      
9d80: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9d90: 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29 0a  IOERR | (1<<8)).
9da0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
9db0: 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20  OERR_SHORT_READ 
9dc0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
9dd0: 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a 23  OERR | (2<<8)).#
9de0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9df0: 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20 20  ERR_WRITE       
9e00: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9e10: 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  ERR | (3<<8)).#d
9e20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9e30: 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20 20  RR_FSYNC        
9e40: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9e50: 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  RR | (4<<8)).#de
9e60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
9e70: 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20 20  R_DIR_FSYNC     
9e80: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
9e90: 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65 66  R | (5<<8)).#def
9ea0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
9eb0: 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20 20  _TRUNCATE       
9ec0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
9ed0: 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66 69   | (6<<8)).#defi
9ee0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
9ef0: 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20 20  FSTAT           
9f00: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
9f10: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
9f20: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 55  e SQLITE_IOERR_U
9f30: 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  NLOCK           
9f40: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
9f50: 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (8<<8)).#define
9f60: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52 44   SQLITE_IOERR_RD
9f70: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
9f80: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
9f90: 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (9<<8)).#define 
9fa0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45 4c  SQLITE_IOERR_DEL
9fb0: 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 28  ETE            (
9fc0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
9fd0: 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  10<<8)).#define 
9fe0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
9ff0: 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20 28  CKED           (
a000: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a010: 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  11<<8)).#define 
a020: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f 4d  SQLITE_IOERR_NOM
a030: 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20 28  EM             (
a040: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a050: 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  12<<8)).#define 
a060: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43 43  SQLITE_IOERR_ACC
a070: 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20 28  ESS            (
a080: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a090: 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  13<<8)).#define 
a0a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48 45  SQLITE_IOERR_CHE
a0b0: 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20 28  CKRESERVEDLOCK (
a0c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a0d0: 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  14<<8)).#define 
a0e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f 43  SQLITE_IOERR_LOC
a0f0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
a100: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a110: 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  15<<8)).#define 
a120: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c 4f  SQLITE_IOERR_CLO
a130: 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20 28  SE             (
a140: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a150: 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  16<<8)).#define 
a160: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49 52  SQLITE_IOERR_DIR
a170: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 28  _CLOSE         (
a180: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a190: 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  17<<8)).#define 
a1a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a1b0: 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20 28  OPEN           (
a1c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a1d0: 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  18<<8)).#define 
a1e0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a1f0: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 28  SIZE           (
a200: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a210: 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  19<<8)).#define 
a220: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a230: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 28  LOCK           (
a240: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a250: 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  20<<8)).#define 
a260: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4d  SQLITE_IOERR_SHM
a270: 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20 28  MAP            (
a280: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a290: 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  21<<8)).#define 
a2a0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45 45  SQLITE_IOERR_SEE
a2b0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 28  K              (
a2c0: 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28  SQLITE_IOERR | (
a2d0: 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  22<<8)).#define 
a2e0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53 48  SQLITE_LOCKED_SH
a2f0: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 28  AREDCACHE      (
a300: 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c 20  SQLITE_LOCKED | 
a310: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
a320: 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45 43   SQLITE_BUSY_REC
a330: 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20 20  OVERY           
a340: 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 7c  (SQLITE_BUSY   |
a350: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
a360: 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45  e SQLITE_CANTOPE
a370: 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20 20 20  N_NOTEMPDIR     
a380: 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   (SQLITE_CANTOPE
a390: 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66  N | (1<<8)).#def
a3a0: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
a3b0: 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20 20 20  PEN_ISDIR       
a3c0: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
a3d0: 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  PEN | (2<<8)).#d
a3e0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
a3f0: 52 55 50 54 5f 56 54 41 42 20 20 20 20 20 20 20  RUPT_VTAB       
a400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 52       (SQLITE_COR
a410: 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  RUPT | (1<<8)).#
a420: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
a430: 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52 59 20  ADONLY_RECOVERY 
a440: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45        (SQLITE_RE
a450: 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38 29 29  ADONLY | (1<<8))
a460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a470: 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c 4f 43  READONLY_CANTLOC
a480: 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  K       (SQLITE_
a490: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c 3c 38  READONLY | (2<<8
a4a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a4b0: 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b  E_ABORT_ROLLBACK
a4c0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
a4d0: 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29  E_ABORT | (2<<8)
a4e0: 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  )../*.** CAPI3RE
a4f0: 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46 69 6c  F: Flags For Fil
a500: 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e  e Open Operation
a510: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69  s.**.** These bi
a520: 74 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e 74  t values are int
a530: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e  ended for use in
a540: 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61 72 61   the.** 3rd para
a550: 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  meter to the [sq
a560: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
a570: 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64 0a 2a   interface and.*
a580: 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70 61 72  * in the 4th par
a590: 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ameter to the [s
a5a0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
a5b0: 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65  ] method..*/.#de
a5c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a5d0: 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 20 20  _READONLY       
a5e0: 20 20 30 78 30 30 30 30 30 30 30 31 20 20 2f 2a    0x00000001  /*
a5f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a600: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a610: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a620: 5f 52 45 41 44 57 52 49 54 45 20 20 20 20 20 20  _READWRITE      
a630: 20 20 30 78 30 30 30 30 30 30 30 32 20 20 2f 2a    0x00000002  /*
a640: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a650: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a660: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a670: 5f 43 52 45 41 54 45 20 20 20 20 20 20 20 20 20  _CREATE         
a680: 20 20 30 78 30 30 30 30 30 30 30 34 20 20 2f 2a    0x00000004  /*
a690: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a6a0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a6b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a6c0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20  _DELETEONCLOSE  
a6d0: 20 20 30 78 30 30 30 30 30 30 30 38 20 20 2f 2a    0x00000008  /*
a6e0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a6f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a700: 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 20 20  _EXCLUSIVE      
a710: 20 20 30 78 30 30 30 30 30 30 31 30 20 20 2f 2a    0x00000010  /*
a720: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a730: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a740: 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20 20 20  _AUTOPROXY      
a750: 20 20 30 78 30 30 30 30 30 30 32 30 20 20 2f 2a    0x00000020  /*
a760: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a770: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a780: 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 20 20  _URI            
a790: 20 20 30 78 30 30 30 30 30 30 34 30 20 20 2f 2a    0x00000040  /*
a7a0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a7b0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a7c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a7d0: 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20 20 20  _MEMORY         
a7e0: 20 20 30 78 30 30 30 30 30 30 38 30 20 20 2f 2a    0x00000080  /*
a7f0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
a800: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
a810: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a820: 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20 20 20  _MAIN_DB        
a830: 20 20 30 78 30 30 30 30 30 31 30 30 20 20 2f 2a    0x00000100  /*
a840: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a860: 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20 20 20  _TEMP_DB        
a870: 20 20 30 78 30 30 30 30 30 32 30 30 20 20 2f 2a    0x00000200  /*
a880: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a890: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a8a0: 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20 20 20  _TRANSIENT_DB   
a8b0: 20 20 30 78 30 30 30 30 30 34 30 30 20 20 2f 2a    0x00000400  /*
a8c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a8d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a8e0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20  _MAIN_JOURNAL   
a8f0: 20 20 30 78 30 30 30 30 30 38 30 30 20 20 2f 2a    0x00000800  /*
a900: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a910: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a920: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20  _TEMP_JOURNAL   
a930: 20 20 30 78 30 30 30 30 31 30 30 30 20 20 2f 2a    0x00001000  /*
a940: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a960: 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20  _SUBJOURNAL     
a970: 20 20 30 78 30 30 30 30 32 30 30 30 20 20 2f 2a    0x00002000  /*
a980: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a990: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a9a0: 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20  _MASTER_JOURNAL 
a9b0: 20 20 30 78 30 30 30 30 34 30 30 30 20 20 2f 2a    0x00004000  /*
a9c0: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65   VFS only */.#de
a9d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
a9e0: 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20 20 20  _NOMUTEX        
a9f0: 20 20 30 78 30 30 30 30 38 30 30 30 20 20 2f 2a    0x00008000  /*
aa00: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
aa10: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
aa20: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
aa30: 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20 20 20  _FULLMUTEX      
aa40: 20 20 30 78 30 30 30 31 30 30 30 30 20 20 2f 2a    0x00010000  /*
aa50: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
aa60: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
aa70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
aa80: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
aa90: 20 20 30 78 30 30 30 32 30 30 30 30 20 20 2f 2a    0x00020000  /*
aaa0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
aab0: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
aac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
aad0: 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 20 20  _PRIVATECACHE   
aae0: 20 20 30 78 30 30 30 34 30 30 30 30 20 20 2f 2a    0x00040000  /*
aaf0: 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65 33 5f   Ok for sqlite3_
ab00: 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65  open_v2() */.#de
ab10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e  fine SQLITE_OPEN
ab20: 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  _WAL            
ab30: 20 20 30 78 30 30 30 38 30 30 30 30 20 20 2f 2a    0x00080000  /*
ab40: 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a   VFS only */../*
ab50: 20 52 65 73 65 72 76 65 64 3a 20 20 20 20 20 20   Reserved:      
ab60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
ab70: 20 20 20 30 78 30 30 46 30 30 30 30 30 20 2a 2f     0x00F00000 */
ab80: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
ab90: 3a 20 44 65 76 69 63 65 20 43 68 61 72 61 63 74  : Device Charact
aba0: 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54  eristics.**.** T
abb0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
abc0: 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f 64  teristics method
abd0: 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
abe0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20  _io_methods].** 
abf0: 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73 20 61  object returns a
ac00: 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20  n integer which 
ac10: 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66 20 74  is a vector of t
ac20: 68 65 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20  he these.** bit 
ac30: 76 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e  values expressin
ac40: 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69  g I/O characteri
ac50: 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73  stics of the mas
ac60: 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76  s storage.** dev
ac70: 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74  ice that holds t
ac80: 68 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65  he file that the
ac90: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
aca0: 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20  hods].** refers 
acb0: 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51  to..**.** The SQ
acc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
acd0: 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  C property means
ace0: 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73   that all writes
acf0: 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20   of.** any size 
ad00: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
ad10: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
ad20: 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a  OMICnnn values.*
ad30: 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74  * mean that writ
ad40: 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61  es of blocks tha
ad50: 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20  t are nnn bytes 
ad60: 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61  in size and.** a
ad70: 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  re aligned to an
ad80: 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69   address which i
ad90: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c  s an integer mul
ada0: 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20  tiple of.** nnn 
adb0: 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65  are atomic.  The
adc0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
add0: 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20  FE_APPEND value 
ade0: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68  means.** that wh
adf0: 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  en data is appen
ae00: 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74  ded to a file, t
ae10: 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e  he data is appen
ae20: 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65  ded.** first the
ae30: 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  n the size of th
ae40: 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64  e file is extend
ae50: 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74  ed, never the ot
ae60: 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e  her.** way aroun
ae70: 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  d.  The SQLITE_I
ae80: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
ae90: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
aea0: 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  hat.** informati
aeb0: 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f  on is written to
aec0: 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d   disk in the sam
aed0: 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73  e order as calls
aee0: 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e  .** to xWrite().
aef0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
af00: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
af10: 52 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20  RWRITE property 
af20: 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66  means that.** af
af30: 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f  ter reboot follo
af40: 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20  wing a crash or 
af50: 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20  power loss, the 
af60: 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a  only bytes in a.
af70: 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72  ** file that wer
af80: 65 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65  e written at the
af90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76   application lev
afa0: 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68  el might have ch
afb0: 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61  anged.** and tha
afc0: 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73  t adjacent bytes
afd0: 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74  , even bytes wit
afe0: 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63  hin the same sec
aff0: 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61  tor are.** guara
b000: 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68  nteed to be unch
b010: 61 6e 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e  anged..*/.#defin
b020: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
b030: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
b040: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
b050: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b060: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
b070: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
b080: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
b090: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
b0a0: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
b0b0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
b0c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
b0d0: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
b0e0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
b0f0: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
b100: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
b110: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
b120: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
b130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
b140: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
b150: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
b160: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
b170: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
b180: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
b190: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
b1a0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
b1b0: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
b1c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
b1d0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b1e0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
b1f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
b200: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
b210: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
b220: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
b230: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
b240: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
b250: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
b260: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
b270: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
b280: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
b290: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
b2a0: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64  N  0x00000800.#d
b2b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
b2c0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
b2d0: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30  RWRITE    0x0000
b2e0: 31 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  1000../*.** CAPI
b2f0: 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69  3REF: File Locki
b300: 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20  ng Levels.**.** 
b310: 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20  SQLite uses one 
b320: 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67 65 72  of these integer
b330: 20 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73   values as the s
b340: 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  econd.** argumen
b350: 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61  t to calls it ma
b360: 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b  kes to the xLock
b370: 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29  () and xUnlock()
b380: 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61   methods.** of a
b390: 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  n [sqlite3_io_me
b3a0: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a  thods] object..*
b3b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
b3c0: 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20  _LOCK_NONE      
b3d0: 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
b3e0: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
b3f0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
b400: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45  e SQLITE_LOCK_RE
b410: 53 45 52 56 45 44 20 20 20 20 20 20 32 0a 23 64  SERVED      2.#d
b420: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43  efine SQLITE_LOC
b430: 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20  K_PENDING       
b440: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
b450: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20  _LOCK_EXCLUSIVE 
b460: 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50      4../*.** CAP
b470: 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69  I3REF: Synchroni
b480: 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67  zation Type Flag
b490: 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c  s.**.** When SQL
b4a0: 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20  ite invokes the 
b4b0: 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f  xSync() method o
b4c0: 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  f an.** [sqlite3
b4d0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  _io_methods] obj
b4e0: 65 63 74 20 69 74 20 75 73 65 73 20 61 20 63 6f  ect it uses a co
b4f0: 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20  mbination of.** 
b500: 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76 61  these integer va
b510: 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63 6f  lues as the seco
b520: 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  nd argument..**.
b530: 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49  ** When the SQLI
b540: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
b550: 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69   flag is used, i
b560: 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
b570: 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69  .** sync operati
b580: 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f  on only needs to
b590: 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d   flush data to m
b5a0: 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e  ass storage.  In
b5b0: 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  ode.** informati
b5c0: 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66  on need not be f
b5d0: 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c  lushed. If the l
b5e0: 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f  ower four bits o
b5f0: 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71  f the flag.** eq
b600: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
b610: 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61  NORMAL, that mea
b620: 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c  ns to use normal
b630: 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69   fsync() semanti
b640: 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f  cs..** If the lo
b650: 77 65 72 20 66 6f 75 72 20 62 69 74 73 20 65 71  wer four bits eq
b660: 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ual SQLITE_SYNC_
b670: 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  FULL, that means
b680: 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f  .** to use Mac O
b690: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
b6a0: 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73  nc instead of fs
b6b0: 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20  ync()..**.** Do 
b6c0: 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20  not confuse the 
b6d0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d  SQLITE_SYNC_NORM
b6e0: 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59  AL and SQLITE_SY
b6f0: 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a  NC_FULL flags.**
b700: 20 77 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d   with the [PRAGM
b710: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e  A synchronous]=N
b720: 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d  ORMAL and [PRAGM
b730: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46  A synchronous]=F
b740: 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e  ULL.** settings.
b750: 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f    The [synchrono
b760: 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72  us pragma] deter
b770: 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73  mines when calls
b780: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63   to the.** xSync
b790: 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75   VFS method occu
b7a0: 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e  r and applies un
b7b0: 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61  iformly across a
b7c0: 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a  ll platforms..**
b7d0: 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   The SQLITE_SYNC
b7e0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
b7f0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
b800: 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77  gs determine how
b810: 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72  .** energetic or
b820: 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72   rigorous or for
b830: 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f  ceful the sync o
b840: 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e  perations are an
b850: 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61  d.** only make a
b860: 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d   difference on M
b870: 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64  ac OSX for the d
b880: 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f  efault SQLite co
b890: 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61  de..** (Third-pa
b8a0: 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  rty VFS implemen
b8b0: 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c  tations might al
b8c0: 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74  so make the dist
b8d0: 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65  inction.** betwe
b8e0: 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  en SQLITE_SYNC_N
b8f0: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
b900: 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20  _SYNC_FULL, but 
b910: 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65  among the.** ope
b920: 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e  rating systems n
b930: 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65  atively supporte
b940: 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c  d by SQLite, onl
b950: 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72  y Mac OSX.** car
b960: 65 73 20 61 62 6f 75 74 20 74 68 65 20 64 69 66  es about the dif
b970: 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65  ference.).*/.#de
b980: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43  fine SQLITE_SYNC
b990: 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30  _NORMAL        0
b9a0: 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53  x00002.#define S
b9b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20  QLITE_SYNC_FULL 
b9c0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 33           0x00003
b9d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b9e0: 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20  SYNC_DATAONLY   
b9f0: 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a     0x00010../*.*
ba00: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
ba10: 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69  nterface Open Fi
ba20: 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  le Handle.**.** 
ba30: 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  An [sqlite3_file
ba40: 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  ] object represe
ba50: 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  nts an open file
ba60: 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c   in the .** [sql
ba70: 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e  ite3_vfs | OS in
ba80: 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20  terface layer]. 
ba90: 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69   Individual OS i
baa0: 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c  nterface.** impl
bab0: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c  ementations will
bac0: 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63  .** want to subc
bad0: 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74  lass this object
bae0: 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64   by appending ad
baf0: 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a  ditional fields.
bb00: 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e  ** for their own
bb10: 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68   use.  The pMeth
bb20: 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61 20 70  ods entry is a p
bb30: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
bb40: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
bb50: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74  ods] object that
bb60: 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73   defines methods
bb70: 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a   for performing.
bb80: 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  ** I/O operation
bb90: 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69  s on the open fi
bba0: 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  le..*/.typedef s
bbb0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
bbc0: 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b  le sqlite3_file;
bbd0: 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f  .struct sqlite3_
bbe0: 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73  file {.  const s
bbf0: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f  truct sqlite3_io
bc00: 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f  _methods *pMetho
bc10: 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  ds;  /* Methods 
bc20: 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65  for an open file
bc30: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
bc40: 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72  PI3REF: OS Inter
bc50: 66 61 63 65 20 46 69 6c 65 20 56 69 72 74 75 61  face File Virtua
bc60: 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74  l Methods Object
bc70: 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c  .**.** Every fil
bc80: 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20  e opened by the 
bc90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
bca0: 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c  en] method popul
bcb0: 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69  ates an.** [sqli
bcc0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
bcd0: 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f   (or, more commo
bce0: 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20  nly, a subclass 
bcf0: 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  of the.** [sqlit
bd00: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29  e3_file] object)
bd10: 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
bd20: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
bd30: 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a  f this object..*
bd40: 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65  * This object de
bd50: 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64  fines the method
bd60: 73 20 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72  s used to perfor
bd70: 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74  m various operat
bd80: 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20  ions.** against 
bd90: 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65  the open file re
bda0: 70 72 65 73 65 6e 74 65 64 20 62 79 20 74 68 65  presented by the
bdb0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
bdc0: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66  object..**.** If
bdd0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
bde0: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
bdf0: 73 65 74 73 20 74 68 65 20 73 71 6c 69 74 65 33  sets the sqlite3
be00: 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65  _file.pMethods e
be10: 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20  lement .** to a 
be20: 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
be30: 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  , then the sqlit
be40: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43  e3_io_methods.xC
be50: 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d  lose method.** m
be60: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76  ay be invoked ev
be70: 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  en if the [sqlit
be80: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65  e3_vfs.xOpen] re
be90: 70 6f 72 74 65 64 20 74 68 61 74 20 69 74 20 66  ported that it f
bea0: 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f  ailed.  The.** o
beb0: 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65 76 65  nly way to preve
bec0: 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c  nt a call to xCl
bed0: 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ose following a 
bee0: 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f  failed [sqlite3_
bef0: 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73  vfs.xOpen].** is
bf00: 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65   for the [sqlite
bf10: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20  3_vfs.xOpen] to 
bf20: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
bf30: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c  file.pMethods el
bf40: 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  ement.** to NULL
bf50: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
bf60: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53  s argument to xS
bf70: 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f  ync may be one o
bf80: 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  f [SQLITE_SYNC_N
bf90: 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51  ORMAL] or.** [SQ
bfa0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e  LITE_SYNC_FULL].
bfb0: 20 20 54 68 65 20 66 69 72 73 74 20 63 68 6f 69    The first choi
bfc0: 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c  ce is the normal
bfd0: 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65   fsync()..** The
bfe0: 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69   second choice i
bff0: 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79  s a Mac OS X sty
c000: 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68  le fullsync.  Th
c010: 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  e [SQLITE_SYNC_D
c020: 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67  ATAONLY].** flag
c030: 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20   may be ORed in 
c040: 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
c050: 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f   only the data o
c060: 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e  f the file.** an
c070: 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20  d not its inode 
c080: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63  needs to be sync
c090: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ed..**.** The in
c0a0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20  teger values to 
c0b0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
c0c0: 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66  ock() are one of
c0d0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
c0e0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
c0f0: 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  NE],.** <li> [SQ
c100: 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44  LITE_LOCK_SHARED
c110: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
c120: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
c130: 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  ],.** <li> [SQLI
c140: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
c150: 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  , or.** <li> [SQ
c160: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
c170: 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  IVE]..** </ul>.*
c180: 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61  * xLock() increa
c190: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55  ses the lock. xU
c1a0: 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65  nlock() decrease
c1b0: 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54  s the lock..** T
c1c0: 68 65 20 78 43 68 65 63 6b 52 65 73 65 72 76 65  he xCheckReserve
c1d0: 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63  dLock() method c
c1e0: 68 65 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e  hecks whether an
c1f0: 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  y database conne
c200: 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72  ction,.** either
c210: 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73   in this process
c220: 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65   or in some othe
c230: 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f  r process, is ho
c240: 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56 45 44  lding a RESERVED
c250: 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72  ,.** PENDING, or
c260: 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20   EXCLUSIVE lock 
c270: 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74  on the file.  It
c280: 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a   returns true.**
c290: 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20   if such a lock 
c2a0: 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65  exists and false
c2b0: 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a   otherwise..**.*
c2c0: 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  * The xFileContr
c2d0: 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61  ol() method is a
c2e0: 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61   generic interfa
c2f0: 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63  ce that allows c
c300: 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70  ustom.** VFS imp
c310: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20  lementations to 
c320: 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c  directly control
c330: 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73   an open file us
c340: 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  ing the.** [sqli
c350: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
c360: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20  ()] interface.  
c370: 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20  The second "op" 
c380: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a  argument is an.*
c390: 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65  * integer opcode
c3a0: 2e 20 20 54 68 65 20 74 68 69 72 64 20 61 72 67  .  The third arg
c3b0: 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72  ument is a gener
c3c0: 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e  ic pointer inten
c3d0: 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20  ded to.** point 
c3e0: 74 6f 20 61 20 73 74 72 75 63 74 75 72 65 20 74  to a structure t
c3f0: 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20  hat may contain 
c400: 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61  arguments or spa
c410: 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a  ce in which to.*
c420: 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e 20 76  * write return v
c430: 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61  alues.  Potentia
c440: 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65  l uses for xFile
c450: 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20  Control() might 
c460: 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  be.** functions 
c470: 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69  to enable blocki
c480: 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69  ng locks with ti
c490: 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67  meouts, to chang
c4a0: 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67  e the.** locking
c4b0: 20 73 74 72 61 74 65 67 79 20 28 66 6f 72 20 65   strategy (for e
c4c0: 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f  xample to use do
c4d0: 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74  t-file locks), t
c4e0: 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f  o inquire.** abo
c4f0: 75 74 20 74 68 65 20 73 74 61 74 75 73 20 6f 66  ut the status of
c500: 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62   a lock, or to b
c510: 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73  reak stale locks
c520: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a  .  The SQLite.**
c530: 20 63 6f 72 65 20 72 65 73 65 72 76 65 73 20 61   core reserves a
c540: 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20  ll opcodes less 
c550: 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73  than 100 for its
c560: 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b   own use..** A [
c570: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
c580: 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66  KSTATE | list of
c590: 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74   opcodes] less t
c5a0: 68 61 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c  han 100 is avail
c5b0: 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61  able..** Applica
c5c0: 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e  tions that defin
c5d0: 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65  e a custom xFile
c5e0: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73  Control method s
c5f0: 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65  hould use opcode
c600: 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61  s.** greater tha
c610: 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63  n 100 to avoid c
c620: 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69  onflicts.  VFS i
c630: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
c640: 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20  hould.** return 
c650: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
c660: 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72  ] for file contr
c670: 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20  ol opcodes that 
c680: 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72  they do not.** r
c690: 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20  ecognize..**.** 
c6a0: 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28  The xSectorSize(
c6b0: 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73  ) method returns
c6c0: 20 74 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   the sector size
c6d0: 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63   of the.** devic
c6e0: 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73  e that underlies
c6f0: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
c700: 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74  sector size is t
c710: 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72  he.** minimum wr
c720: 69 74 65 20 74 68 61 74 20 63 61 6e 20 62 65 20  ite that can be 
c730: 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75  performed withou
c740: 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20  t disturbing.** 
c750: 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e 20 74  other bytes in t
c760: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44  he file.  The xD
c770: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
c780: 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  tics().** method
c790: 20 72 65 74 75 72 6e 73 20 61 20 62 69 74 20 76   returns a bit v
c7a0: 65 63 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67  ector describing
c7b0: 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68   behaviors of th
c7c0: 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20  e.** underlying 
c7d0: 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75  device:.**.** <u
c7e0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  l>.** <li> [SQLI
c7f0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d  TE_IOCAP_ATOMIC]
c800: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c810: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32  _IOCAP_ATOMIC512
c820: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
c830: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
c840: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
c850: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b  E_IOCAP_ATOMIC2K
c860: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
c870: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b  E_IOCAP_ATOMIC4K
c880: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
c890: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b  E_IOCAP_ATOMIC8K
c8a0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
c8b0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36  E_IOCAP_ATOMIC16
c8c0: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
c8d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
c8e0: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
c8f0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
c900: 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  64K].** <li> [SQ
c910: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
c920: 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20  APPEND].** <li> 
c930: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45  [SQLITE_IOCAP_SE
c940: 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75  QUENTIAL].** </u
c950: 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  l>.**.** The SQL
c960: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
c970: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
c980: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
c990: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
c9a0: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
c9b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
c9c0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
c9d0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
c9e0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
c9f0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
ca00: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
ca10: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
ca20: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
ca30: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
ca40: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
ca50: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
ca60: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
ca70: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
ca80: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
ca90: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
caa0: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
cab0: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
cac0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
cad0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
cae0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
caf0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
cb00: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
cb10: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
cb20: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
cb30: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
cb40: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
cb50: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
cb60: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
cb70: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
cb80: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a  ** to xWrite()..
cb90: 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29  **.** If xRead()
cba0: 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f   returns SQLITE_
cbb0: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
cbc0: 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69   it must also fi
cbd0: 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72  ll.** in the unr
cbe0: 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20  ead portions of 
cbf0: 74 68 65 20 62 75 66 66 65 72 20 77 69 74 68 20  the buffer with 
cc00: 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68  zeros.  A VFS th
cc10: 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a  at.** fails to z
cc20: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
cc30: 65 61 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20  eads might seem 
cc40: 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65  to work.  Howeve
cc50: 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f  r,.** failure to
cc60: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
cc70: 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e   reads will even
cc80: 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a  tually lead to.*
cc90: 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72 72 75  * database corru
cca0: 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65  ption..*/.typede
ccb0: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
ccc0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69  _io_methods sqli
ccd0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a  te3_io_methods;.
cce0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
ccf0: 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e  o_methods {.  in
cd00: 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e  t iVersion;.  in
cd10: 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
cd20: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
cd30: 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74  t (*xRead)(sqlit
cd40: 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c  e3_file*, void*,
cd50: 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74   int iAmt, sqlit
cd60: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b  e3_int64 iOfst);
cd70: 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29  .  int (*xWrite)
cd80: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
cd90: 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
cda0: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
cdb0: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
cdc0: 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28  nt (*xTruncate)(
cdd0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
cde0: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a  qlite3_int64 siz
cdf0: 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e  e);.  int (*xSyn
ce00: 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  c)(sqlite3_file*
ce10: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
ce20: 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29  int (*xFileSize)
ce30: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
ce40: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70  sqlite3_int64 *p
ce50: 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  Size);.  int (*x
ce60: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
ce70: 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74  le*, int);.  int
ce80: 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69   (*xUnlock)(sqli
ce90: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b  te3_file*, int);
cea0: 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52  .  int (*xCheckR
ceb0: 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c  eservedLock)(sql
cec0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
ced0: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
cee0: 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29   (*xFileControl)
cef0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
cf00: 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41  int op, void *pA
cf10: 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65  rg);.  int (*xSe
cf20: 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65  ctorSize)(sqlite
cf30: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
cf40: 28 2a 78 44 65 76 69 63 65 43 68 61 72 61 63 74  (*xDeviceCharact
cf50: 65 72 69 73 74 69 63 73 29 28 73 71 6c 69 74 65  eristics)(sqlite
cf60: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d  3_file*);.  /* M
cf70: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
cf80: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
cf90: 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  on 1 */.  int (*
cfa0: 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33  xShmMap)(sqlite3
cfb0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c  _file*, int iPg,
cfc0: 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20   int pgsz, int, 
cfd0: 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29  void volatile**)
cfe0: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f  ;.  int (*xShmLo
cff0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
d000: 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69  *, int offset, i
d010: 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29  nt n, int flags)
d020: 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42  ;.  void (*xShmB
d030: 61 72 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f  arrier)(sqlite3_
d040: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
d050: 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74  xShmUnmap)(sqlit
d060: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65  e3_file*, int de
d070: 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20  leteFlag);.  /* 
d080: 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  Methods above ar
d090: 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73  e valid for vers
d0a0: 69 6f 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64  ion 2 */.  /* Ad
d0b0: 64 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73  ditional methods
d0c0: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
d0d0: 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
d0e0: 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
d0f0: 50 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64  PI3REF: Standard
d100: 20 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70   File Control Op
d110: 63 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  codes.**.** Thes
d120: 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61  e integer consta
d130: 6e 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20  nts are opcodes 
d140: 66 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  for the xFileCon
d150: 74 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  trol method.** o
d160: 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  f the [sqlite3_i
d170: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
d180: 74 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73  t and for the [s
d190: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
d1a0: 72 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  rol()].** interf
d1b0: 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  ace..**.** The [
d1c0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43  SQLITE_FCNTL_LOC
d1d0: 4b 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69  KSTATE] opcode i
d1e0: 73 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67  s used for debug
d1f0: 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f  ging.  This.** o
d200: 70 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65  pcode causes the
d210: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
d220: 74 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68  thod to write th
d230: 65 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20  e current state 
d240: 6f 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28  of.** the lock (
d250: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c  one of [SQLITE_L
d260: 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49  OCK_NONE], [SQLI
d270: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
d280: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  .** [SQLITE_LOCK
d290: 5f 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c  _RESERVED], [SQL
d2a0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
d2b0: 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f  ], or [SQLITE_LO
d2c0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a  CK_EXCLUSIVE]).*
d2d0: 2a 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65  * into an intege
d2e0: 72 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20  r that the pArg 
d2f0: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
d300: 74 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c  to. This capabil
d310: 69 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64  ity.** is used d
d320: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e  uring testing an
d330: 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20  d only needs to 
d340: 62 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65  be supported whe
d350: 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a  n SQLITE_TEST.**
d360: 20 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20   is defined..** 
d370: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  <ul>.** <li>[[SQ
d380: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
d390: 48 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53  HINT]].** The [S
d3a0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
d3b0: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
d3c0: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
d3d0: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
d3e0: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
d3f0: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
d400: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
d410: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
d420: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
d430: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
d440: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
d450: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
d460: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
d470: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
d480: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
d490: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
d4a0: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
d4b0: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
d4c0: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
d4d0: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
d4e0: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
d4f0: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
d500: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
d510: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
d520: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
d530: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
d540: 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  E]].** The [SQLI
d550: 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53  TE_FCNTL_CHUNK_S
d560: 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  IZE] opcode is u
d570: 73 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74  sed to request t
d580: 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65  hat the VFS.** e
d590: 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63  xtends and trunc
d5a0: 61 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73  ates the databas
d5b0: 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73  e file in chunks
d5c0: 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69   of a size speci
d5d0: 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75  fied.** by the u
d5e0: 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20  ser. The fourth 
d5f0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c  argument to [sql
d600: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
d610: 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20  l()] should .** 
d620: 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65  point to an inte
d630: 67 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63  ger (type int) c
d640: 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65  ontaining the ne
d650: 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20  w chunk-size to 
d660: 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e  use.** for the n
d670: 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73  ominated databas
d680: 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61  e. Allocating da
d690: 74 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63  tabase file spac
d6a0: 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68  e in large.** ch
d6b0: 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74  unks (say 1MB at
d6c0: 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65   a time), may re
d6d0: 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d  duce file-system
d6e0: 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61   fragmentation a
d6f0: 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65  nd.** improve pe
d700: 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d  rformance on som
d710: 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a  e systems..**.**
d720: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d730: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
d740: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
d750: 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49  E_FCNTL_FILE_POI
d760: 4e 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20  NTER] opcode is 
d770: 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61  used to obtain a
d780: 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
d790: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
d7a0: 5d 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61  ] object associa
d7b0: 74 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69  ted with a parti
d7c0: 63 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a  cular database.*
d7d0: 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53  * connection.  S
d7e0: 65 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  ee the [sqlite3_
d7f0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
d800: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
d810: 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
d820: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
d830: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
d840: 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54  FCNTL_SYNC_OMITT
d850: 45 44 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53  ED]].** ^(The [S
d860: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43  QLITE_FCNTL_SYNC
d870: 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65  _OMITTED] opcode
d880: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
d890: 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53  ternally by.** S
d8a0: 51 4c 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74  QLite and sent t
d8b0: 6f 20 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70  o all VFSes in p
d8c0: 6c 61 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74  lace of a call t
d8d0: 6f 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  o the xSync meth
d8e0: 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64  od.** when the d
d8f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d900: 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73  on has [PRAGMA s
d910: 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20  ynchronous] set 
d920: 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d  to OFF.)^.** Som
d930: 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46  e specialized VF
d940: 53 65 73 20 6e 65 65 64 20 74 68 69 73 20 73 69  Ses need this si
d950: 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f  gnal in order to
d960: 20 6f 70 65 72 61 74 65 20 63 6f 72 72 65 63 74   operate correct
d970: 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47  ly.** when [PRAG
d980: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
d990: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
d9a0: 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c  ous=OFF] is set,
d9b0: 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46   but most .** VF
d9c0: 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20  Ses do not need 
d9d0: 74 68 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20  this signal and 
d9e0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
d9f0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
da00: 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  de..** Applicati
da10: 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63  ons should not c
da20: 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  all [sqlite3_fil
da30: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
da40: 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65  h this.** opcode
da50: 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79   as doing so may
da60: 20 64 69 73 72 75 70 74 20 74 68 65 20 6f 70 65   disrupt the ope
da70: 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70  ration of the sp
da80: 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a  ecialized VFSes.
da90: 2a 2a 20 74 68 61 74 20 64 6f 20 72 65 71 75 69  ** that do requi
daa0: 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c  re it.  .**.** <
dab0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
dac0: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
dad0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
dae0: 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41  TE_FCNTL_WIN32_A
daf0: 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20  V_RETRY] opcode 
db00: 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
db10: 67 75 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a  gure automatic.*
db20: 2a 20 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61  * retry counts a
db30: 6e 64 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72  nd intervals for
db40: 20 63 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f   certain disk I/
db50: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72  O operations for
db60: 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20   the.** windows 
db70: 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74  [VFS] in order t
db80: 6f 20 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74  o provide robust
db90: 6e 65 73 73 20 69 6e 20 74 68 65 20 70 72 65 73  ness in the pres
dba0: 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d  ence of.** anti-
dbb0: 76 69 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20  virus programs. 
dbc0: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
dbd0: 20 77 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c   windows VFS wil
dbe0: 6c 20 72 65 74 72 79 20 66 69 6c 65 20 72 65 61  l retry file rea
dbf0: 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65  d,.** file write
dc00: 2c 20 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74  , and file delet
dc10: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  e operations up 
dc20: 74 6f 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74  to 10 times, wit
dc30: 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20  h a delay.** of 
dc40: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
dc50: 62 65 66 6f 72 65 20 74 68 65 20 66 69 72 73 74  before the first
dc60: 20 72 65 74 72 79 20 61 6e 64 20 77 69 74 68 20   retry and with 
dc70: 74 68 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61  the delay increa
dc80: 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64  sing.** by an ad
dc90: 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c  ditional 25 mill
dca0: 69 73 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61  iseconds with ea
dcb0: 63 68 20 73 75 62 73 65 71 75 65 6e 74 20 72 65  ch subsequent re
dcc0: 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  try.  This.** op
dcd0: 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73  code allows thes
dce0: 65 20 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30  e two values (10
dcf0: 20 72 65 74 72 69 65 73 20 61 6e 64 20 32 35 20   retries and 25 
dd00: 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20  milliseconds of 
dd10: 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20  delay).** to be 
dd20: 61 64 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76  adjusted.  The v
dd30: 61 6c 75 65 73 20 61 72 65 20 63 68 61 6e 67 65  alues are change
dd40: 64 20 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61  d for all databa
dd50: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
dd60: 2a 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  * within the sam
dd70: 65 20 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20  e process.  The 
dd80: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f  argument is a po
dd90: 69 6e 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61  inter to an arra
dda0: 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65  y of two.** inte
ddb0: 67 65 72 73 20 77 68 65 72 65 20 74 68 65 20 66  gers where the f
ddc0: 69 72 73 74 20 69 6e 74 65 67 65 72 20 69 20 74  irst integer i t
ddd0: 68 65 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75  he new retry cou
dde0: 6e 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nt and the secon
ddf0: 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20  d.** integer is 
de00: 74 68 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65  the delay.  If e
de10: 69 74 68 65 72 20 69 6e 74 65 67 65 72 20 69 73  ither integer is
de20: 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
de30: 74 68 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69  the setting.** i
de40: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75  s not changed bu
de50: 74 20 69 6e 73 74 65 61 64 20 74 68 65 20 70 72  t instead the pr
de60: 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61  ior value of tha
de70: 74 20 73 65 74 74 69 6e 67 20 69 73 20 77 72 69  t setting is wri
de80: 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  tten.** into the
de90: 20 61 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c   array entry, al
dea0: 6c 6f 77 69 6e 67 20 74 68 65 20 63 75 72 72 65  lowing the curre
deb0: 6e 74 20 72 65 74 72 79 20 73 65 74 74 69 6e 67  nt retry setting
dec0: 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72  s to be.** inter
ded0: 72 6f 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44  rogated.  The zD
dee0: 62 4e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  bName parameter 
def0: 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
df00: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
df10: 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c  CNTL_PERSIST_WAL
df20: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
df30: 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54  TE_FCNTL_PERSIST
df40: 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20  _WAL] opcode is 
df50: 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71  used to set or q
df60: 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73  uery the.** pers
df70: 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72  istent [WAL | Wr
df80: 69 74 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73  ite Ahead Log] s
df90: 65 74 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61  etting.  By defa
dfa0: 75 6c 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61  ult, the auxilia
dfb0: 72 79 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61  ry.** write ahea
dfc0: 64 20 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64  d log and shared
dfd0: 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73   memory files us
dfe0: 65 64 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69  ed for transacti
dff0: 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72  on control.** ar
e000: 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
e010: 64 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65  deleted when the
e020: 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69   latest connecti
e030: 6f 6e 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  on to the databa
e040: 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53  se.** closes.  S
e050: 65 74 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e  etting persisten
e060: 74 20 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65  t WAL mode cause
e070: 73 20 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f  s those files to
e080: 20 70 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a   persist after.*
e090: 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73  * close.  Persis
e0a0: 74 69 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69  ting the files i
e0b0: 73 20 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74  s useful when ot
e0c0: 68 65 72 20 70 72 6f 63 65 73 73 65 73 20 74 68  her processes th
e0d0: 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76  at do not.** hav
e0e0: 65 20 77 72 69 74 65 20 70 65 72 6d 69 73 73 69  e write permissi
e0f0: 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74  on on the direct
e100: 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  ory containing t
e110: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
e120: 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64   want.** to read
e130: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
e140: 6c 65 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61  le, as the WAL a
e150: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
e160: 20 66 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73   files must exis
e170: 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f  t.** in order fo
e180: 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 74  r the database t
e190: 6f 20 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20  o be readable.  
e1a0: 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
e1b0: 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
e1c0: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
e1d0: 28 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63  ()] for this opc
e1e0: 6f 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ode should be a 
e1f0: 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
e200: 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69  teger..** That i
e210: 6e 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64  nteger is 0 to d
e220: 69 73 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e  isable persisten
e230: 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20  t WAL mode or 1 
e240: 74 6f 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73  to enable persis
e250: 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65  tent.** WAL mode
e260: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
e270: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
e280: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
e290: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
e2a0: 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65  .** WAL persiste
e2b0: 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a  nce setting..**.
e2c0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
e2d0: 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f  FCNTL_POWERSAFE_
e2e0: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
e2f0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
e300: 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  L_POWERSAFE_OVER
e310: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
e320: 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20   used to set or 
e330: 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72  query the.** per
e340: 73 69 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61  sistent "powersa
e350: 66 65 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72  fe-overwrite" or
e360: 20 22 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e   "PSOW" setting.
e370: 20 20 54 68 65 20 50 53 4f 57 20 73 65 74 74 69    The PSOW setti
e380: 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73  ng.** determines
e390: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43   the [SQLITE_IOC
e3a0: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
e3b0: 52 57 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74  RWRITE] bit of t
e3c0: 68 65 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61  he.** xDeviceCha
e3d0: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
e3e0: 68 6f 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68  hods. The fourth
e3f0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
e400: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
e410: 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68  ontrol()] for th
e420: 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64  is opcode should
e430: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
e440: 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20   an integer..** 
e450: 54 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20  That integer is 
e460: 30 20 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72  0 to disable zer
e470: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72  o-damage mode or
e480: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72   1 to enable zer
e490: 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65  o-damage.** mode
e4a0: 2e 20 20 49 66 20 74 68 65 20 69 6e 74 65 67 65  .  If the intege
e4b0: 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74  r is -1, then it
e4c0: 20 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20   is overwritten 
e4d0: 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
e4e0: 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20  .** zero-damage 
e4f0: 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a  mode setting..**
e500: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
e510: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
e520: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
e530: 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49  TE_FCNTL_OVERWRI
e540: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e  TE] opcode is in
e550: 76 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20  voked by SQLite 
e560: 61 66 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a  after opening.**
e570: 20 61 20 77 72 69 74 65 20 74 72 61 6e 73 61 63   a write transac
e580: 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  tion to indicate
e590: 20 74 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74   that, unless it
e5a0: 20 69 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   is rolled back 
e5b0: 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73  for some.** reas
e5c0: 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64  on, the entire d
e5d0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
e5e0: 6c 20 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e  l be overwritten
e5f0: 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74 20   by the current 
e600: 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  .** transaction.
e610: 20 54 68 69 73 20 69 73 20 75 73 65 64 20 62 79   This is used by
e620: 20 56 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f   VACUUM operatio
e630: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ns..**.** <li>[[
e640: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
e650: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b  NAME]].** ^The [
e660: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
e670: 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e  NAME] opcode can
e680: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61   be used to obta
e690: 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a  in the names of.
e6a0: 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69  ** all [VFSes] i
e6b0: 6e 20 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e  n the VFS stack.
e6c0: 20 20 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20    The names are 
e6d0: 6f 66 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73  of all VFS shims
e6e0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61   and the.** fina
e6f0: 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56  l bottom-level V
e700: 46 53 20 61 72 65 20 77 72 69 74 74 65 6e 20 69  FS are written i
e710: 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69  nto memory obtai
e720: 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71  ned from .** [sq
e730: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
e740: 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 20 69  and the result i
e750: 73 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20  s stored in the 
e760: 63 68 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a  char* variable.*
e770: 2a 20 74 68 61 74 20 74 68 65 20 66 6f 75 72 74  * that the fourt
e780: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b  h parameter of [
e790: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
e7a0: 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74  trol()] points t
e7b0: 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72  o..** The caller
e7c0: 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
e7d0: 66 6f 72 20 66 72 65 65 69 6e 67 20 74 68 65 20  for freeing the 
e7e0: 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65  memory when done
e7f0: 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c  .  As with.** al
e800: 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61  l file-control a
e810: 63 74 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73  ctions, there is
e820: 20 6e 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68   no guarantee th
e830: 61 74 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74  at this will act
e840: 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74  ually.** do anyt
e850: 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73  hing.  Callers s
e860: 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65  hould initialize
e870: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
e880: 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a  ble to a NULL.**
e890: 20 70 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65   pointer in case
e8a0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
e8b0: 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d  ol is not implem
e8c0: 65 6e 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c  ented.  This fil
e8d0: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20  e-control.** is 
e8e0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61  intended for dia
e8f0: 67 6e 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79  gnostic use only
e900: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
e910: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
e920: 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72  A]].** ^Whenever
e930: 20 61 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74   a [PRAGMA] stat
e940: 65 6d 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c  ement is parsed,
e950: 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54   an [SQLITE_FCNT
e960: 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69  L_PRAGMA] .** fi
e970: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65  le control is se
e980: 6e 74 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b  nt to the open [
e990: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
e9a0: 6a 65 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69  ject correspondi
e9b0: 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74  ng.** to the dat
e9c0: 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68  abase file to wh
e9d0: 69 63 68 20 74 68 65 20 70 72 61 67 6d 61 20 73  ich the pragma s
e9e0: 74 61 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e  tatement refers.
e9f0: 20 5e 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a   ^The argument.*
ea00: 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45  * to the [SQLITE
ea10: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
ea20: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61  ile control is a
ea30: 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f  n array of.** po
ea40: 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67  inters to string
ea50: 73 20 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68  s (char**) in wh
ea60: 69 63 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ich the second e
ea70: 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72  lement of the ar
ea80: 72 61 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ray.** is the na
ea90: 6d 65 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  me of the pragma
eaa0: 20 61 6e 64 20 74 68 65 20 74 68 69 72 64 20 65   and the third e
eab0: 6c 65 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72  lement is the ar
eac0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
ead0: 20 70 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20   pragma or NULL 
eae0: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 68 61  if the pragma ha
eaf0: 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20  s no argument.  
eb00: 5e 54 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72  ^The handler for
eb10: 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46   an.** [SQLITE_F
eb20: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
eb30: 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70  e control can op
eb40: 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68  tionally make th
eb50: 65 20 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a  e first element.
eb60: 2a 2a 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a  ** of the char**
eb70: 20 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20   argument point 
eb80: 74 6f 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61  to a string obta
eb90: 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
eba0: 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a  e3_mprintf()].**
ebb0: 20 6f 72 20 74 68 65 20 65 71 75 69 76 61 6c 65   or the equivale
ebc0: 6e 74 20 61 6e 64 20 74 68 61 74 20 73 74 72 69  nt and that stri
ebd0: 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74  ng will become t
ebe0: 68 65 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65  he result of the
ebf0: 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68   pragma or.** th
ec00: 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  e error message 
ec10: 69 66 20 74 68 65 20 70 72 61 67 6d 61 20 66 61  if the pragma fa
ec20: 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20  ils. ^If the.** 
ec30: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ec40: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ec50: 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ol returns [SQLI
ec60: 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68  TE_NOTFOUND], th
ec70: 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50  en normal .** [P
ec80: 52 41 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e  RAGMA] processin
ec90: 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49  g continues.  ^I
eca0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
ecb0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66  NTL_PRAGMA].** f
ecc0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
ecd0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c  rns [SQLITE_OK],
ece0: 20 74 68 65 6e 20 74 68 65 20 70 61 72 73 65 72   then the parser
ecf0: 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
ed00: 65 0a 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e  e.** VFS has han
ed10: 64 6c 65 64 20 74 68 65 20 50 52 41 47 4d 41 20  dled the PRAGMA 
ed20: 69 74 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70  itself and the p
ed30: 61 72 73 65 72 20 67 65 6e 65 72 61 74 65 73 20  arser generates 
ed40: 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61  a no-op.** prepa
ed50: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  red statement.  
ed60: 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ^If the [SQLITE_
ed70: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
ed80: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
ed90: 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74  ns.** any result
eda0: 20 63 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e   code other than
edb0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
edc0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
edd0: 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a  ], that means.**
ede0: 20 74 68 61 74 20 74 68 65 20 56 46 53 20 65 6e   that the VFS en
edf0: 63 6f 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72  countered an err
ee00: 6f 72 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e  or while handlin
ee10: 67 20 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61  g the [PRAGMA] a
ee20: 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c  nd the.** compil
ee30: 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41  ation of the PRA
ee40: 47 4d 41 20 66 61 69 6c 73 20 77 69 74 68 20 61  GMA fails with a
ee50: 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b  n error.  ^The [
ee60: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
ee70: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
ee80: 74 72 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74  trol occurs at t
ee90: 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
eea0: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
eeb0: 20 61 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f   analysis and so
eec0: 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74  .** it is able t
eed0: 6f 20 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74  o override built
eee0: 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61  -in [PRAGMA] sta
eef0: 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f 75 6c  tements..** </ul
ef00: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
ef10: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
ef20: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
ef30: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
ef40: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
ef50: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
ef60: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
ef70: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
ef80: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
ef90: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
efa0: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
efb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34                 4
efc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
efd0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
efe0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
eff0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
f000: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
f010: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
f020: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
f030: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
f040: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
f050: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
f060: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
f070: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
f080: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
f090: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
f0a0: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
f0b0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
f0c0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
f0d0: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
f0e0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
f0f0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
f100: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
f110: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
f120: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
f130: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
f140: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
f150: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
f160: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
f170: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
f180: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
f190: 20 20 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41      14../*.** CA
f1a0: 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61  PI3REF: Mutex Ha
f1b0: 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d  ndle.**.** The m
f1c0: 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68  utex module with
f1d0: 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65  in SQLite define
f1e0: 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  s [sqlite3_mutex
f1f0: 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62  ] to be an.** ab
f200: 73 74 72 61 63 74 20 74 79 70 65 20 66 6f 72 20  stract type for 
f210: 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20  a mutex object. 
f220: 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
f230: 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20   never looks.** 
f240: 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  at the internal 
f250: 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f  representation o
f260: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75  f an [sqlite3_mu
f270: 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a  tex].  It only.*
f280: 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69  * deals with poi
f290: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71  nters to the [sq
f2a0: 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a  lite3_mutex] obj
f2b0: 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78  ect..**.** Mutex
f2c0: 65 73 20 61 72 65 20 63 72 65 61 74 65 64 20 75  es are created u
f2d0: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  sing [sqlite3_mu
f2e0: 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  tex_alloc()]..*/
f2f0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
f300: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71  sqlite3_mutex sq
f310: 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a  lite3_mutex;../*
f320: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
f330: 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63   Interface Objec
f340: 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  t.**.** An insta
f350: 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74  nce of the sqlit
f360: 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65  e3_vfs object de
f370: 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66  fines the interf
f380: 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74  ace between.** t
f390: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61  he SQLite core a
f3a0: 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e  nd the underlyin
f3b0: 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  g operating syst
f3c0: 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a  em.  The "vfs".*
f3d0: 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  * in the name of
f3e0: 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e   the object stan
f3f0: 64 73 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20  ds for "virtual 
f400: 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53  file system".  S
f410: 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c  ee.** the [VFS |
f420: 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69   VFS documentati
f430: 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20  on] for further 
f440: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
f450: 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20  ** The value of 
f460: 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65  the iVersion fie
f470: 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20  ld is initially 
f480: 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72  1 but may be lar
f490: 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  ger in.** future
f4a0: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
f4b0: 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c  ite.  Additional
f4c0: 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61   fields may be a
f4d0: 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a  ppended to this.
f4e0: 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74  ** object when t
f4f0: 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75  he iVersion valu
f500: 65 20 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20  e is increased. 
f510: 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 73   Note that the s
f520: 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74  tructure.** of t
f530: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  he sqlite3_vfs o
f540: 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e  bject changes in
f550: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
f560: 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69   between.** SQLi
f570: 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39  te version 3.5.9
f580: 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79   and 3.6.0 and y
f590: 65 74 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  et the iVersion 
f5a0: 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a  field was not.**
f5b0: 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a   modified..**.**
f5c0: 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69   The szOsFile fi
f5d0: 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a 65 20  eld is the size 
f5e0: 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73 73 65  of the subclasse
f5f0: 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  d [sqlite3_file]
f600: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 75 73  .** structure us
f610: 65 64 20 62 79 20 74 68 69 73 20 56 46 53 2e 20  ed by this VFS. 
f620: 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74   mxPathname is t
f630: 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
f640: 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61  h of.** a pathna
f650: 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a  me in this VFS..
f660: 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64  **.** Registered
f670: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
f680: 65 63 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e  ects are kept on
f690: 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66   a linked list f
f6a0: 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20  ormed by.** the 
f6b0: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20  pNext pointer.  
f6c0: 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  The [sqlite3_vfs
f6d0: 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20  _register()].** 
f6e0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  and [sqlite3_vfs
f6f0: 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69  _unregister()] i
f700: 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65  nterfaces manage
f710: 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e   this list.** in
f720: 20 61 20 74 68 72 65 61 64 2d 73 61 66 65 20 77   a thread-safe w
f730: 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ay.  The [sqlite
f740: 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e  3_vfs_find()] in
f750: 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63  terface.** searc
f760: 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e  hes the list.  N
f770: 65 69 74 68 65 72 20 74 68 65 20 61 70 70 6c 69  either the appli
f780: 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20  cation code nor 
f790: 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65  the VFS.** imple
f7a0: 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64  mentation should
f7b0: 20 75 73 65 20 74 68 65 20 70 4e 65 78 74 20 70   use the pNext p
f7c0: 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  ointer..**.** Th
f7d0: 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73  e pNext field is
f7e0: 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20   the only field 
f7f0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76  in the sqlite3_v
f800: 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  fs.** structure 
f810: 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
f820: 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53   ever modify.  S
f830: 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20  QLite will only 
f840: 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64  access.** or mod
f850: 69 66 79 20 74 68 69 73 20 66 69 65 6c 64 20 77  ify this field w
f860: 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70  hile holding a p
f870: 61 72 74 69 63 75 6c 61 72 20 73 74 61 74 69 63  articular static
f880: 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61   mutex..** The a
f890: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
f8a0: 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61  d never modify a
f8b0: 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74  nything within t
f8c0: 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a  he sqlite3_vfs.*
f8d0: 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68  * object once th
f8e0: 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65  e object has bee
f8f0: 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a  n registered..**
f900: 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69  .** The zName fi
f910: 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61  eld holds the na
f920: 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f  me of the VFS mo
f930: 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20  dule.  The name 
f940: 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75  must.** be uniqu
f950: 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53  e across all VFS
f960: 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20   modules..**.** 
f970: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f  [[sqlite3_vfs.xO
f980: 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65  pen]].** ^SQLite
f990: 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
f9a0: 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70   the zFilename p
f9b0: 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65  arameter to xOpe
f9c0: 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61  n.** is either a
f9d0: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72   NULL pointer or
f9e0: 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64   string obtained
f9f0: 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61  .** from xFullPa
fa00: 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e  thname() with an
fa10: 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78   optional suffix
fa20: 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61   added..** ^If a
fa30: 20 73 75 66 66 69 78 20 69 73 20 61 64 64 65 64   suffix is added
fa40: 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d   to the zFilenam
fa50: 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20  e parameter, it 
fa60: 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20  will.** consist 
fa70: 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20  of a single "-" 
fa80: 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77  character follow
fa90: 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68  ed by no more th
faa0: 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75  an.** 11 alphanu
fab0: 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22  meric and/or "-"
fac0: 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20   characters..** 
fad0: 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65 72 20  ^SQLite further 
fae0: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a  guarantees that.
faf0: 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 77 69  ** the string wi
fb00: 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20  ll be valid and 
fb10: 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20  unchanged until 
fb20: 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63  xClose() is.** c
fb30: 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f  alled. Because o
fb40: 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 73  f the previous s
fb50: 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  entence,.** the 
fb60: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63  [sqlite3_file] c
fb70: 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20  an safely store 
fb80: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
fb90: 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20  .** filename if 
fba0: 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65  it needs to reme
fbb0: 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d  mber the filenam
fbc0: 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f  e for some reaso
fbd0: 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69  n..** If the zFi
fbe0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
fbf0: 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e   to xOpen is a N
fc00: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
fc10: 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69   xOpen.** must i
fc20: 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65  nvent its own te
fc30: 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72  mporary name for
fc40: 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65   the file.  ^Whe
fc50: 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46  never the .** xF
fc60: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
fc70: 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c  r is NULL it wil
fc80: 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61  l also be the ca
fc90: 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66  se that the.** f
fca0: 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 77  lags parameter w
fcb0: 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  ill include [SQL
fcc0: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
fcd0: 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54  NCLOSE]..**.** T
fce0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
fcf0: 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63  t to xOpen() inc
fd00: 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73  ludes all bits s
fd10: 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61  et in.** the fla
fd20: 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b  gs argument to [
fd30: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
fd40: 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69  )].  Or if [sqli
fd50: 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f  te3_open()].** o
fd60: 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  r [sqlite3_open1
fd70: 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68  6()] is used, th
fd80: 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65  en flags include
fd90: 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53  s at least.** [S
fda0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
fdb0: 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
fdc0: 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a  OPEN_CREATE]. .*
fdd0: 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65  * If xOpen() ope
fde0: 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f  ns a file read-o
fdf0: 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65 74 73  nly then it sets
fe00: 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a   *pOutFlags to.*
fe10: 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  * include [SQLIT
fe20: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
fe30: 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e  .  Other bits in
fe40: 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20   *pOutFlags may 
fe50: 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28  be set..**.** ^(
fe60: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
fe70: 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20   add one of the 
fe80: 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20  following flags 
fe90: 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a  to the xOpen().*
fea0: 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e  * call, dependin
feb0: 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20  g on the object 
fec0: 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a  being opened:.**
fed0: 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ul>.** <li>
fee0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d    [SQLITE_OPEN_M
fef0: 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  AIN_DB].** <li> 
ff00: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
ff10: 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c  IN_JOURNAL].** <
ff20: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
ff30: 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_TEMP_DB].** <l
ff40: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ff50: 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _TEMP_JOURNAL].*
ff60: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
ff70: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
ff80: 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  B].** <li>  [SQL
ff90: 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52  ITE_OPEN_SUBJOUR
ffa0: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
ffb0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45  QLITE_OPEN_MASTE
ffc0: 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c  R_JOURNAL].** <l
ffd0: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ffe0: 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  _WAL].** </ul>)^
fff0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20  .**.** The file 
10000 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  I/O implementati
10010 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f  on can use the o
10020 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61 67 73  bject type flags
10030 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68   to.** change th
10040 65 20 77 61 79 20 69 74 20 64 65 61 6c 73 20 77  e way it deals w
10050 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20  ith files.  For 
10060 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c  example, an appl
10070 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20  ication.** that 
10080 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62  does not care ab
10090 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f 76 65  out crash recove
100a0 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d  ry or rollback m
100b0 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65  ight make.** the
100c0 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e   open of a journ
100d0 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e  al file a no-op.
100e0 20 20 57 72 69 74 65 73 20 74 6f 20 74 68 69 73    Writes to this
100f0 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a   journal would.*
10100 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73  * also be no-ops
10110 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70  , and any attemp
10120 74 20 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f  t to read the jo
10130 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75  urnal would retu
10140 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45  rn.** SQLITE_IOE
10150 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c  RR.  Or the impl
10160 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74  ementation might
10170 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20   recognize that 
10180 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  a database.** fi
10190 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67  le will be doing
101a0 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65   page-aligned se
101b0 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77  ctor reads and w
101c0 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f  rites in a rando
101d0 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73  m.** order and s
101e0 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75  et up its I/O su
101f0 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e  bsystem accordin
10200 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  gly..**.** SQLit
10210 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64  e might also add
10220 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c   one of the foll
10230 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74  owing flags to t
10240 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a  he xOpen method:
10250 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
10260 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  li> [SQLITE_OPEN
10270 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
10280 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
10290 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a  OPEN_EXCLUSIVE].
102a0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54  ** </ul>.**.** T
102b0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
102c0 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66  DELETEONCLOSE] f
102d0 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69  lag means the fi
102e0 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  le should be.** 
102f0 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20  deleted when it 
10300 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65  is closed.  ^The
10310 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
10320 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20  LETEONCLOSE].** 
10330 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20  will be set for 
10340 54 45 4d 50 20 64 61 74 61 62 61 73 65 73 20 61  TEMP databases a
10350 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c  nd their journal
10360 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20  s, transient.** 
10370 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73  databases, and s
10380 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a  ubjournals..**.*
10390 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
103a0 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66  PEN_EXCLUSIVE] f
103b0 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20 75 73  lag is always us
103c0 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f  ed in conjunctio
103d0 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53  n.** with the [S
103e0 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
103f0 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61  E] flag, which a
10400 72 65 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79  re both directly
10410 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f  .** analogous to
10420 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20   the O_EXCL and 
10430 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66  O_CREAT flags of
10440 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28   the POSIX open(
10450 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53  ).** API.  The S
10460 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55  QLITE_OPEN_EXCLU
10470 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20  SIVE flag, when 
10480 70 61 69 72 65 64 20 77 69 74 68 20 74 68 65 20  paired with the 
10490 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  .** SQLITE_OPEN_
104a0 43 52 45 41 54 45 2c 20 69 73 20 75 73 65 64 20  CREATE, is used 
104b0 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68 61 74  to indicate that
104c0 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77   file should alw
104d0 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65  ays.** be create
104e0 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74 20 69  d, and that it i
104f0 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74  s an error if it
10500 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e   already exists.
10510 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74  .** It is <i>not
10520 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64  </i> used to ind
10530 69 63 61 74 65 20 74 68 65 20 66 69 6c 65 20 73  icate the file s
10540 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20  hould be opened 
10550 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76  .** for exclusiv
10560 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20  e access..**.** 
10570 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69  ^At least szOsFi
10580 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  le bytes of memo
10590 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64  ry are allocated
105a0 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f   by SQLite.** to
105b0 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69   hold the  [sqli
105c0 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74  te3_file] struct
105d0 75 72 65 20 70 61 73 73 65 64 20 61 73 20 74 68  ure passed as th
105e0 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d  e third.** argum
105f0 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54  ent to xOpen.  T
10600 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20  he xOpen method 
10610 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f  does not have to
10620 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65  .** allocate the
10630 20 73 74 72 75 63 74 75 72 65 3b 20 69 74 20 73   structure; it s
10640 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20  hould just fill 
10650 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61  it in.  Note tha
10660 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d  t.** the xOpen m
10670 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74  ethod must set t
10680 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
10690 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68  pMethods to eith
106a0 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73  er.** a valid [s
106b0 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
106c0 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20  s] object or to 
106d0 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73  NULL.  xOpen mus
106e0 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65  t do.** this eve
106f0 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61  n if the open fa
10700 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70  ils.  SQLite exp
10710 65 63 74 73 20 74 68 61 74 20 74 68 65 20 73 71  ects that the sq
10720 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
10730 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77  ods.** element w
10740 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74  ill be valid aft
10750 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73  er xOpen returns
10760 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74   regardless of t
10770 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72  he success.** or
10780 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20   failure of the 
10790 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  xOpen call..**.*
107a0 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
107b0 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68  xAccess]].** ^Th
107c0 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
107d0 20 74 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61   to xAccess() ma
107e0 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43  y be [SQLITE_ACC
107f0 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74  ESS_EXISTS].** t
10800 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65 20 65  o test for the e
10810 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69  xistence of a fi
10820 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41  le, or [SQLITE_A
10830 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d  CCESS_READWRITE]
10840 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74   to.** test whet
10850 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 72 65  her a file is re
10860 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
10870 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ble, or [SQLITE_
10880 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20  ACCESS_READ].** 
10890 74 6f 20 74 65 73 74 20 77 68 65 74 68 65 72 20  to test whether 
108a0 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61  a file is at lea
108b0 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54  st readable.   T
108c0 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61  he file can be a
108d0 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  .** directory..*
108e0 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c  *.** ^SQLite wil
108f0 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74  l always allocat
10900 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74  e at least mxPat
10910 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f  hname+1 bytes fo
10920 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20  r the.** output 
10930 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68  buffer xFullPath
10940 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74  name.  The exact
10950 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74   size of the out
10960 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73  put buffer.** is
10970 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20   also passed as 
10980 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62  a parameter to b
10990 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66  oth  methods. If
109a0 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66 66   the output buff
109b0 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72  er.** is not lar
109c0 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49  ge enough, [SQLI
109d0 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f  TE_CANTOPEN] sho
109e0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
109f0 20 53 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a   Since this is.*
10a00 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66  * handled as a f
10a10 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51  atal error by SQ
10a20 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d  Lite, vfs implem
10a30 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  entations should
10a40 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20   endeavor.** to 
10a50 70 72 65 76 65 6e 74 20 74 68 69 73 20 62 79 20  prevent this by 
10a60 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61  setting mxPathna
10a70 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63 69 65  me to a sufficie
10a80 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65  ntly large value
10a90 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e  ..**.** The xRan
10aa0 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65  domness(), xSlee
10ab0 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d  p(), xCurrentTim
10ac0 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e  e(), and xCurren
10ad0 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20  tTimeInt64().** 
10ae0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 6e  interfaces are n
10af0 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20 70 61  ot strictly a pa
10b00 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79  rt of the filesy
10b10 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61  stem, but they a
10b20 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69  re.** included i
10b30 6e 20 74 68 65 20 56 46 53 20 73 74 72 75 63 74  n the VFS struct
10b40 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65  ure for complete
10b50 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61  ness..** The xRa
10b60 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74  ndomness() funct
10b70 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20  ion attempts to 
10b80 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79  return nBytes by
10b90 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71  tes.** of good-q
10ba0 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73  uality randomnes
10bb0 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68  s into zOut.  Th
10bc0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69  e return value i
10bd0 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20  s.** the actual 
10be0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
10bf0 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62  of randomness ob
10c00 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78  tained..** The x
10c10 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63  Sleep() method c
10c20 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e  auses the callin
10c30 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65  g thread to slee
10c40 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73  p for at.** leas
10c50 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
10c60 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76  microseconds giv
10c70 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65  en.  ^The xCurre
10c80 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68  ntTime().** meth
10c90 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c  od returns a Jul
10ca0 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66  ian Day Number f
10cb0 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  or the current d
10cc0 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a  ate and time as.
10cd0 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ** a floating po
10ce0 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54  int value..** ^T
10cf0 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
10d00 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65  nt64() method re
10d10 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74  turns, as an int
10d20 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e  eger, the Julian
10d30 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d  .** Day Number m
10d40 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38 36 34  ultiplied by 864
10d50 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65  00000 (the numbe
10d60 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  r of millisecond
10d70 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f  s in .** a 24-ho
10d80 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53  ur day).  .** ^S
10d90 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
10da0 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49  he xCurrentTimeI
10db0 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f  nt64() method to
10dc0 20 67 65 74 20 74 68 65 20 63 75 72 72 65 6e 74   get the current
10dd0 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d  .** date and tim
10de0 65 20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64  e if that method
10df0 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69   is available (i
10e00 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20  f iVersion is 2 
10e10 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61  or .** greater a
10e20 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  nd the function 
10e30 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
10e40 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61  ULL) and will fa
10e50 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43  ll back.** to xC
10e60 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20  urrentTime() if 
10e70 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
10e80 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62  4() is unavailab
10e90 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  le..**.** ^The x
10ea0 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  SetSystemCall(),
10eb0 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xGetSystemCall(
10ec0 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74  ), and xNestSyst
10ed0 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61  emCall() interfa
10ee0 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75  ces.** are not u
10ef0 73 65 64 20 62 79 20 74 68 65 20 53 51 4c 69 74  sed by the SQLit
10f00 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f  e core.  These o
10f10 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63  ptional interfac
10f20 65 73 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a  es are provided.
10f30 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73  ** by some VFSes
10f40 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74   to facilitate t
10f50 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46  esting of the VF
10f60 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72  S code. By overr
10f70 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d  iding .** system
10f80 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63   calls with func
10f90 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20  tions under its 
10fa0 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20  control, a test 
10fb0 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73  program can.** s
10fc0 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61  imulate faults a
10fd0 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69  nd error conditi
10fe0 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f  ons that would o
10ff0 74 68 65 72 77 69 73 65 20 62 65 20 64 69 66 66  therwise be diff
11000 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f  icult.** or impo
11010 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65  ssible to induce
11020 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20 73 79  .  The set of sy
11030 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20  stem calls that 
11040 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65  can be overridde
11050 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d  n.** varies from
11060 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74   one VFS to anot
11070 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e  her, and from on
11080 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65  e version of the
11090 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65   same VFS to the
110a0 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  .** next.  Appli
110b0 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65  cations that use
110c0 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
110d0 73 20 6d 75 73 74 20 62 65 20 70 72 65 70 61 72  s must be prepar
110e0 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72  ed for any.** or
110f0 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e   all of these in
11100 74 65 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e  terfaces to be N
11110 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72  ULL or for their
11120 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61   behavior to cha
11130 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20  nge.** from one 
11140 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e  release to the n
11150 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ext.  Applicatio
11160 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65  ns must not atte
11170 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a  mpt to access.**
11180 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65   any of these me
11190 74 68 6f 64 73 20 69 66 20 74 68 65 20 69 56 65  thods if the iVe
111a0 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53  rsion of the VFS
111b0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e   is less than 3.
111c0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
111d0 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73  ct sqlite3_vfs s
111e0 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65  qlite3_vfs;.type
111f0 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
11200 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28  e3_syscall_ptr)(
11210 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71  void);.struct sq
11220 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e  lite3_vfs {.  in
11230 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20  t iVersion;     
11240 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74         /* Struct
11250 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62  ure version numb
11260 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29  er (currently 3)
11270 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69   */.  int szOsFi
11280 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f  le;            /
11290 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61  * Size of subcla
112a0 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c  ssed sqlite3_fil
112b0 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74  e */.  int mxPat
112c0 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20  hname;          
112d0 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20  /* Maximum file 
112e0 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20  pathname length 
112f0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73  */.  sqlite3_vfs
11300 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a   *pNext;      /*
11310 20 4e 65 78 74 20 72 65 67 69 73 74 65 72 65 64   Next registered
11320 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20   VFS */.  const 
11330 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20  char *zName;    
11340 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68     /* Name of th
11350 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20  is virtual file 
11360 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64  system */.  void
11370 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20   *pAppData;     
11380 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20       /* Pointer 
11390 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73  to application-s
113a0 70 65 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a  pecific data */.
113b0 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73    int (*xOpen)(s
113c0 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
113d0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
113e0 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20  sqlite3_file*,. 
113f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 69 6e                in
11400 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f  t flags, int *pO
11410 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  utFlags);.  int 
11420 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74  (*xDelete)(sqlit
11430 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
11440 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
11450 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20  syncDir);.  int 
11460 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c 69 74  (*xAccess)(sqlit
11470 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
11480 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
11490 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73  flags, int *pRes
114a0 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46  Out);.  int (*xF
114b0 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c  ullPathname)(sql
114c0 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
114d0 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
114e0 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f  t nOut, char *zO
114f0 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78  ut);.  void *(*x
11500 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  DlOpen)(sqlite3_
11510 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
11520 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20   *zFilename);.  
11530 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29  void (*xDlError)
11540 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
11550 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
11560 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64  zErrMsg);.  void
11570 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c   (*(*xDlSym)(sql
11580 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c  ite3_vfs*,void*,
11590 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79   const char *zSy
115a0 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20  mbol))(void);.  
115b0 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29  void (*xDlClose)
115c0 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76  (sqlite3_vfs*, v
115d0 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  oid*);.  int (*x
115e0 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69  Randomness)(sqli
115f0 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42  te3_vfs*, int nB
11600 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29  yte, char *zOut)
11610 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70  ;.  int (*xSleep
11620 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
11630 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73  int microseconds
11640 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  );.  int (*xCurr
11650 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33  entTime)(sqlite3
11660 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b  _vfs*, double*);
11670 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73  .  int (*xGetLas
11680 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f  tError)(sqlite3_
11690 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20  vfs*, int, char 
116a0 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68  *);.  /*.  ** Th
116b0 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  e methods above 
116c0 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31  are in version 1
116d0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
116e0 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64  fs object.  ** d
116f0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73  efinition.  Thos
11700 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72  e that follow ar
11710 65 20 61 64 64 65 64 20 69 6e 20 76 65 72 73 69  e added in versi
11720 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20  on 2 or later.  
11730 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72  */.  int (*xCurr
11740 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71  entTimeInt64)(sq
11750 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69  lite3_vfs*, sqli
11760 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f  te3_int64*);.  /
11770 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
11780 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
11790 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32  versions 1 and 2
117a0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76   of the sqlite_v
117b0 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20  fs object..  ** 
117c0 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20  Those below are 
117d0 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e  for version 3 an
117e0 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a  d greater..  */.
117f0 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74    int (*xSetSyst
11800 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
11810 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
11820 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
11830 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20  _syscall_ptr);. 
11840 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c   sqlite3_syscall
11850 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73 74 65  _ptr (*xGetSyste
11860 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76  mCall)(sqlite3_v
11870 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  fs*, const char 
11880 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74  *zName);.  const
11890 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79   char *(*xNextSy
118a0 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
118b0 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
118c0 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a  ar *zName);.  /*
118d0 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64  .  ** The method
118e0 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76  s above are in v
118f0 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67  ersions 1 throug
11900 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74  h 3 of the sqlit
11910 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20  e_vfs object..  
11920 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61  ** New fields ma
11930 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e  y be appended in
11940 20 66 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73   figure versions
11950 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a  .  The iVersion.
11960 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20    ** value will 
11970 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76  increment whenev
11980 65 72 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e  er this happens.
11990 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a   .  */.};../*.**
119a0 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73   CAPI3REF: Flags
119b0 20 66 6f 72 20 74 68 65 20 78 41 63 63 65 73 73   for the xAccess
119c0 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a   VFS method.**.*
119d0 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20  * These integer 
119e0 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65  constants can be
119f0 20 75 73 65 64 20 61 73 20 74 68 65 20 74 68 69   used as the thi
11a00 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  rd parameter to.
11a10 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ** the xAccess m
11a20 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c  ethod of an [sql
11a30 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
11a40 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e  .  They determin
11a50 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f  e.** what kind o
11a60 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68  f permissions th
11a70 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64  e xAccess method
11a80 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e   is looking for.
11a90 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
11aa0 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74  ACCESS_EXISTS, t
11ab0 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
11ac0 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63  d.** simply chec
11ad0 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
11ae0 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57  ile exists..** W
11af0 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ith SQLITE_ACCES
11b00 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74 68 65  S_READWRITE, the
11b10 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
11b20 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
11b30 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65  r the named dire
11b40 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65  ctory is both re
11b50 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61  adable and writa
11b60 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72  ble.** (in other
11b70 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73   words, if files
11b80 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72   can be added, r
11b90 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61  emoved, and rena
11ba0 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68  med within.** th
11bb0 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a  e directory)..**
11bc0 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45   The SQLITE_ACCE
11bd0 53 53 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e  SS_READWRITE con
11be0 73 74 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74  stant is current
11bf0 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20  ly used only by 
11c00 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f  the.** [temp_sto
11c10 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61  re_directory pra
11c20 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69  gma], though thi
11c30 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69  s could change i
11c40 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65  n a future.** re
11c50 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
11c60 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
11c70 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65  ACCESS_READ, the
11c80 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
11c90 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74 68 65  ** checks whethe
11ca0 72 20 74 68 65 20 66 69 6c 65 20 69 73 20 72 65  r the file is re
11cb0 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c  adable.  The SQL
11cc0 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20  ITE_ACCESS_READ 
11cd0 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63  constant is.** c
11ce0 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c  urrently unused,
11cf0 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74   though it might
11d00 20 62 65 20 75 73 65 64 20 69 6e 20 61 20 66 75   be used in a fu
11d10 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a  ture release of.
11d20 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  ** SQLite..*/.#d
11d30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
11d40 45 53 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a  ESS_EXISTS    0.
11d50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
11d60 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20  CCESS_READWRITE 
11d70 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50  1   /* Used by P
11d80 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65  RAGMA temp_store
11d90 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64  _directory */.#d
11da0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
11db0 45 53 53 5f 52 45 41 44 20 20 20 20 20 20 32 20  ESS_READ      2 
11dc0 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a    /* Unused */..
11dd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
11de0 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 53  Flags for the xS
11df0 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f  hmLock VFS metho
11e00 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  d.**.** These in
11e10 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
11e20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f  define the vario
11e30 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61  us locking opera
11e40 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64  tions.** allowed
11e50 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b   by the xShmLock
11e60 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69   method of [sqli
11e70 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e  te3_io_methods].
11e80 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69    The.** followi
11e90 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20  ng are the only 
11ea0 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f  legal combinatio
11eb0 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74  ns of flags to t
11ec0 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d  he.** xShmLock m
11ed0 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  ethod:.**.** <ul
11ee0 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54  >.** <li>  SQLIT
11ef0 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c  E_SHM_LOCK | SQL
11f00 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a  ITE_SHM_SHARED.*
11f10 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
11f20 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  HM_LOCK | SQLITE
11f30 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a  _SHM_EXCLUSIVE.*
11f40 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53  * <li>  SQLITE_S
11f50 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49  HM_UNLOCK | SQLI
11f60 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a  TE_SHM_SHARED.**
11f70 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48   <li>  SQLITE_SH
11f80 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  M_UNLOCK | SQLIT
11f90 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a  E_SHM_EXCLUSIVE.
11fa0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57  ** </ul>.**.** W
11fb0 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74  hen unlocking, t
11fc0 68 65 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f  he same SHARED o
11fd0 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67  r EXCLUSIVE flag
11fe0 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c 69 65   must be supplie
11ff0 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65  d as.** was give
12000 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70  n no the corresp
12010 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a  onding lock.  .*
12020 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63  *.** The xShmLoc
12030 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61  k method can tra
12040 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20  nsition between 
12050 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41  unlocked and SHA
12060 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65  RED or.** betwee
12070 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45  n unlocked and E
12080 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61  XCLUSIVE.  It ca
12090 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20  nnot transition 
120a0 62 65 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a  between SHARED.*
120b0 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e  * and EXCLUSIVE.
120c0 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
120d0 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20  TE_SHM_UNLOCK   
120e0 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
120f0 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20  LITE_SHM_LOCK   
12100 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
12110 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45  SQLITE_SHM_SHARE
12120 44 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e  D       4.#defin
12130 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43  e SQLITE_SHM_EXC
12140 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a  LUSIVE    8../*.
12150 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78  ** CAPI3REF: Max
12160 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e  imum xShmLock in
12170 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  dex.**.** The xS
12180 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e  hmLock method on
12190 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
121a0 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61  hods] may use va
121b0 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
121c0 30 20 61 6e 64 20 74 68 69 73 20 75 70 70 65 72  0 and this upper
121d0 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f   bound as its "o
121e0 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e  ffset" argument.
121f0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
12200 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61  ore will never a
12210 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72  ttempt to acquir
12220 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a  e or release a.*
12230 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f  * lock outside o
12240 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a  f this range.*/.
12250 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
12260 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  HM_NLOCK        
12270 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  8.../*.** CAPI3R
12280 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54  EF: Initialize T
12290 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
122a0 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  y.**.** ^The sql
122b0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
122c0 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61  ) routine initia
122d0 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c  lizes the.** SQL
122e0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54  ite library.  ^T
122f0 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  he sqlite3_shutd
12300 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a  own() routine.**
12310 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79   deallocates any
12320 20 72 65 73 6f 75 72 63 65 73 20 74 68 61 74 20   resources that 
12330 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  were allocated b
12340 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  y sqlite3_initia
12350 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65  lize()..** These
12360 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65   routines are de
12370 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e  signed to aid in
12380 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c   process initial
12390 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73  ization and.** s
123a0 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64  hutdown on embed
123b0 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f  ded systems.  Wo
123c0 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63  rkstation applic
123d0 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20  ations using.** 
123e0 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20  SQLite normally 
123f0 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69  do not need to i
12400 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20  nvoke either of 
12410 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
12420 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20  **.** A call to 
12430 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12440 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  ze() is an "effe
12450 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
12460 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73  t is.** the firs
12470 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
12480 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
12490 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68  nvoked during th
124a0 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a  e lifetime of.**
124b0 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72   the process, or
124c0 20 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69   if it is the fi
124d0 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
124e0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
124f0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c   invoked.** foll
12500 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20  owing a call to 
12510 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12520 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65  ().  ^(Only an e
12530 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a  ffective call.**
12540 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   of sqlite3_init
12550 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e  ialize() does an
12560 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
12570 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c  .  All other cal
12580 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65  ls.** are harmle
12590 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a  ss no-ops.)^.**.
125a0 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  ** A call to sql
125b0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
125c0 69 73 20 61 6e 20 22 65 66 66 65 63 74 69 76 65  is an "effective
125d0 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20  " call if it is 
125e0 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c  the first.** cal
125f0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
12600 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68  tdown() since th
12610 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69  e last sqlite3_i
12620 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28  nitialize().  ^(
12630 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63  Only.** an effec
12640 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c  tive call to sql
12650 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20  ite3_shutdown() 
12660 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69  does any deiniti
12670 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c  alization..** Al
12680 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61  l other valid ca
12690 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  lls to sqlite3_s
126a0 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61  hutdown() are ha
126b0 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e  rmless no-ops.)^
126c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
126d0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
126e0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 72  interface is thr
126f0 65 61 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c  eadsafe, but sql
12700 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
12710 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20  ** is not.  The 
12720 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
12730 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73  () interface mus
12740 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64  t only be called
12750 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c   from a.** singl
12760 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f  e thread.  All o
12770 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
12780 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20  nnections] must 
12790 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c  be closed and al
127a0 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74  l.** other SQLit
127b0 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74  e resources must
127c0 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
127d0 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e  prior to invokin
127e0 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75  g.** sqlite3_shu
127f0 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41  tdown()..**.** A
12800 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67  mong other thing
12810 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74  s, ^sqlite3_init
12820 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e  ialize() will in
12830 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
12840 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69  os_init().  Simi
12850 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f  larly, ^sqlite3_
12860 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69  shutdown().** wi
12870 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ll invoke sqlite
12880 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a  3_os_end()..**.*
12890 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
128a0 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
128b0 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ine returns [SQL
128c0 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
128d0 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73  ss..** ^If for s
128e0 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69  ome reason, sqli
128f0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12900 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e   is unable to in
12910 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20  itialize.** the 
12920 6c 69 62 72 61 72 79 20 28 70 65 72 68 61 70 73  library (perhaps
12930 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
12940 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64   allocate a need
12950 65 64 20 72 65 73 6f 75 72 63 65 20 73 75 63 68  ed resource such
12960 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20  .** as a mutex) 
12970 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65  it returns an [e
12980 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72  rror code] other
12990 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
129a0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ]..**.** ^The sq
129b0 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
129c0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  () routine is ca
129d0 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  lled internally 
129e0 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a  by many other.**
129f0 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
12a00 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70  es so that an ap
12a10 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c  plication usuall
12a20 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  y does not need 
12a30 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c  to.** invoke sql
12a40 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12a50 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72  ) directly.  For
12a60 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74   example, [sqlit
12a70 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61  e3_open()].** ca
12a80 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  lls sqlite3_init
12a90 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20  ialize() so the 
12aa0 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
12ab0 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63  ill be automatic
12ac0 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69  ally.** initiali
12ad0 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65  zed when [sqlite
12ae0 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c  3_open()] is cal
12af0 6c 65 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f  led if it has no
12b00 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64  t be initialized
12b10 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48  .** already.  ^H
12b20 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74  owever, if SQLit
12b30 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12b40 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
12b50 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a  MIT_AUTOINIT].**
12b60 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
12b70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61  tion, then the a
12b80 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74  utomatic calls t
12b90 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
12ba0 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d  lize().** are om
12bb0 69 74 74 65 64 20 61 6e 64 20 74 68 65 20 61 70  itted and the ap
12bc0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63  plication must c
12bd0 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  all sqlite3_init
12be0 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c  ialize() directl
12bf0 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73  y.** prior to us
12c00 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
12c10 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
12c20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72   For maximum por
12c30 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20  tability,.** it 
12c40 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
12c50 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
12c60 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73   always invoke s
12c70 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12c80 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20  e().** directly 
12c90 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61  prior to using a
12ca0 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ny other SQLite 
12cb0 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75 74 75  interface.  Futu
12cc0 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f  re releases.** o
12cd0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71  f SQLite may req
12ce0 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f  uire this.  In o
12cf0 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
12d00 62 65 68 61 76 69 6f 72 20 65 78 68 69 62 69 74  behavior exhibit
12d10 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74  ed.** when SQLit
12d20 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
12d30 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  th [SQLITE_OMIT_
12d40 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20  AUTOINIT] might 
12d50 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65  become the.** de
12d60 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69  fault behavior i
12d70 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
12d80 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
12d90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
12da0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75  e3_os_init() rou
12db0 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74  tine does operat
12dc0 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
12dd0 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a  fic.** initializ
12de0 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c  ation of the SQL
12df0 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68  ite library.  Th
12e00 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  e sqlite3_os_end
12e10 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e  ().** routine un
12e20 64 6f 65 73 20 74 68 65 20 65 66 66 65 63 74 20  does the effect 
12e30 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
12e40 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74  it().  Typical t
12e50 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65  asks.** performe
12e60 64 20 62 79 20 74 68 65 73 65 20 72 6f 75 74 69  d by these routi
12e70 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f  nes include allo
12e80 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f  cation or deallo
12e90 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61  cation.** of sta
12ea0 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69  tic resources, i
12eb0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66  nitialization of
12ec0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
12ed0 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70  s,.** setting up
12ee0 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69   a default [sqli
12ef0 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c  te3_vfs] module,
12f00 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a   or setting up.*
12f10 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  * a default conf
12f20 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20  iguration using 
12f30 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
12f40 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  )]..**.** The ap
12f50 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
12f60 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69   never invoke ei
12f70 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ther sqlite3_os_
12f80 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  init().** or sql
12f90 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69  ite3_os_end() di
12fa0 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70  rectly.  The app
12fb0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
12fc0 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73  only invoke.** s
12fd0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
12fe0 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  e() and sqlite3_
12ff0 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65  shutdown().  The
13000 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
13010 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ().** interface 
13020 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61  is called automa
13030 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
13040 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
13050 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  and.** sqlite3_o
13060 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65  s_end() is calle
13070 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75  d by sqlite3_shu
13080 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70  tdown().  Approp
13090 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65  riate.** impleme
130a0 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ntations for sql
130b0 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
130c0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
130d0 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74  d().** are built
130e0 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65   into SQLite whe
130f0 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  n it is compiled
13100 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f   for Unix, Windo
13110 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20  ws, or OS/2..** 
13120 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69  When [custom bui
13130 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20  lds | built for 
13140 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d  other platforms]
13150 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b  .** (using the [
13160 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d  SQLITE_OS_OTHER=
13170 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a  1] compile-time.
13180 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61  ** option) the a
13190 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
131a0 73 75 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c  supply a suitabl
131b0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
131c0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
131d0 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71  os_init() and sq
131e0 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20  lite3_os_end(). 
131f0 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   An application-
13200 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c  supplied.** impl
13210 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71  ementation of sq
13220 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20  lite3_os_init() 
13230 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  or sqlite3_os_en
13240 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75  d().** must retu
13250 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
13260 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f  n success and so
13270 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20  me other [error 
13280 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61  code] upon.** fa
13290 69 6c 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ilure..*/.SQLITE
132a0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
132b0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64  _initialize(void
132c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
132d0 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
132e0 77 6e 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  wn(void);.SQLITE
132f0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
13300 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a  _os_init(void);.
13310 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
13320 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f  qlite3_os_end(vo
13330 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  id);../*.** CAPI
13340 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e  3REF: Configurin
13350 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62  g The SQLite Lib
13360 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  rary.**.** The s
13370 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
13380 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65  interface is use
13390 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c  d to make global
133a0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a   configuration.*
133b0 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c  * changes to SQL
133c0 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ite in order to 
133d0 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74  tune SQLite to t
133e0 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65 64  he specific need
133f0 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  s of.** the appl
13400 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65  ication.  The de
13410 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74  fault configurat
13420 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ion is recommend
13430 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61  ed for most.** a
13440 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20  pplications and 
13450 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  so this routine 
13460 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e  is usually not n
13470 65 63 65 73 73 61 72 79 2e 20 20 49 74 20 69 73  ecessary.  It is
13480 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20  .** provided to 
13490 73 75 70 70 6f 72 74 20 72 61 72 65 20 61 70 70  support rare app
134a0 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75  lications with u
134b0 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a  nusual needs..**
134c0 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
134d0 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
134e0 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64  ce is not thread
134f0 73 61 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69  safe.  The appli
13500 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69  cation.** must i
13510 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74  nsure that no ot
13520 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
13530 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65  faces are invoke
13540 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68  d by other.** th
13550 72 65 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69  reads while sqli
13560 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20  te3_config() is 
13570 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65  running.  Furthe
13580 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63  rmore, sqlite3_c
13590 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f  onfig().** may o
135a0 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70  nly be invoked p
135b0 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20  rior to library 
135c0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75  initialization u
135d0 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
135e0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f  _initialize()] o
135f0 72 20 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e  r after shutdown
13600 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75   by [sqlite3_shu
13610 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66  tdown()]..** ^If
13620 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
13630 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65  ) is called afte
13640 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  r [sqlite3_initi
13650 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66  alize()] and bef
13660 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ore.** [sqlite3_
13670 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e  shutdown()] then
13680 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20   it will return 
13690 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a  SQLITE_MISUSE..*
136a0 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c  * Note, however,
136b0 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63   that ^sqlite3_c
136c0 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65 20 63  onfig() can be c
136d0 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66  alled as part of
136e0 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e   the.** implemen
136f0 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70  tation of an app
13700 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
13710 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69   [sqlite3_os_ini
13720 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  t()]..**.** The 
13730 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
13740 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  o sqlite3_config
13750 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  () is an integer
13760 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69  .** [configurati
13770 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20  on option] that 
13780 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68  determines.** wh
13790 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53  at property of S
137a0 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65 20 63  QLite is to be c
137b0 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75 62 73  onfigured.  Subs
137c0 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
137d0 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69  .** vary dependi
137e0 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69  ng on the [confi
137f0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
13800 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
13810 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
13820 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
13830 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
13840 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
13850 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
13860 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
13870 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
13880 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
13890 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
138a0 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
138b0 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
138c0 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
138d0 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
138e0 64 65 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  de]..*/.SQLITE_A
138f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
13900 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b  onfig(int, ...);
13910 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13920 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61  : Configure data
13930 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
13940 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
13950 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69  e3_db_config() i
13960 6e 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64  nterface is used
13970 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75   to make configu
13980 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65  ration.** change
13990 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65  s to a [database
139a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
139b0 68 65 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  he interface is 
139c0 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73  similar to.** [s
139d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
139e0 20 65 78 63 65 70 74 20 74 68 61 74 20 74 68 65   except that the
139f0 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74   changes apply t
13a00 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64  o a single.** [d
13a10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
13a20 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64 20 69  on] (specified i
13a30 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
13a40 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ment)..**.** The
13a50 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
13a60 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63   to sqlite3_db_c
13a70 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20  onfig(D,V,...)  
13a80 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  is the.** [SQLIT
13a90 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
13aa0 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61  SIDE | configura
13ab0 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20  tion verb] - an 
13ac0 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a  integer code .**
13ad0 20 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20   that indicates 
13ae0 77 68 61 74 20 61 73 70 65 63 74 20 6f 66 20 74  what aspect of t
13af0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
13b00 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e  nection] is bein
13b10 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a  g configured..**
13b20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67 75   Subsequent argu
13b30 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e  ments vary depen
13b40 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66  ding on the conf
13b50 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a  iguration verb..
13b60 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20  **.** ^Calls to 
13b70 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
13b80 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54  g() return SQLIT
13b90 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79  E_OK if and only
13ba0 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20   if.** the call 
13bb0 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75  is considered su
13bc0 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  ccessful..*/.SQL
13bd0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
13be0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
13bf0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
13c00 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
13c10 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
13c20 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
13c30 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
13c40 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
13c50 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
13c60 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
13c70 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
13c80 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
13c90 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
13ca0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
13cb0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
13cc0 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
13cd0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
13ce0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
13cf0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
13d00 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
13d10 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
13d20 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
13d30 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
13d40 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
13d50 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
13d60 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
13d70 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
13d80 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
13d90 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
13da0 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
13db0 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
13dc0 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
13dd0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
13de0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
13df0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
13e00 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
13e10 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
13e20 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
13e30 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
13e40 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
13e50 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
13e60 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
13e70 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
13e80 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
13e90 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
13ea0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
13eb0 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
13ec0 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
13ed0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
13ee0 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
13ef0 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
13f00 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
13f10 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
13f20 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
13f30 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
13f40 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
13f50 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
13f60 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
13f70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
13f80 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
13f90 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13fa0 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
13fb0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
13fc0 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
13fd0 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
13fe0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
13ff0 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
14000 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
14010 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
14020 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
14030 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
14040 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
14050 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
14060 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
14070 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
14080 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
14090 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
140a0 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
140b0 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
140c0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
140d0 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
140e0 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
140f0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
14100 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
14110 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
14120 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
14130 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
14140 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
14150 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
14160 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
14170 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
14180 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
14190 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
141a0 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
141b0 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
141c0 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
141d0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
141e0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
141f0 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
14200 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
14210 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
14220 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
14230 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
14240 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
14250 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
14260 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
14270 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
14280 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
14290 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
142a0 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
142b0 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
142c0 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
142d0 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
142e0 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
142f0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
14300 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
14310 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
14320 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
14330 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
14340 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
14350 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
14360 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
14370 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
14380 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
14390 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
143a0 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
143b0 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
143c0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
143d0 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
143e0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
143f0 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
14400 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
14410 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
14420 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
14430 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
14440 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
14450 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
14460 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
14470 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
14480 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
14490 20 20 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a    (For example,.
144a0 2a 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f  ** it might allo
144b0 63 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65  cate any require
144c0 20 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74   mutexes or init
144d0 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20  ialize internal 
144e0 64 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72  data.** structur
144f0 65 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f  es.  The xShutdo
14500 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76  wn method is inv
14510 6f 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79  oked (indirectly
14520 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ) by.** [sqlite3
14530 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64  _shutdown()] and
14540 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61   should dealloca
14550 74 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73  te any resources
14560 20 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20   acquired.** by 
14570 78 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70  xInit.  The pApp
14580 44 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20  Data pointer is 
14590 75 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79  used as the only
145a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
145b0 20 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74   xInit and xShut
145c0 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  down..**.** SQLi
145d0 74 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  te holds the [SQ
145e0 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
145f0 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20  C_MASTER] mutex 
14600 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a  when it invokes.
14610 2a 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  ** the xInit met
14620 68 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69  hod, so the xIni
14630 74 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f  t method need no
14640 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e  t be threadsafe.
14650 20 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f    The.** xShutdo
14660 77 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c  wn method is onl
14670 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73  y called from [s
14680 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
14690 29 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a  )] so it does.**
146a0 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
146b0 74 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65  threadsafe eithe
146c0 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65  r.  For all othe
146d0 72 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74  r methods, SQLit
146e0 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b  e.** holds the [
146f0 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41  SQLITE_MUTEX_STA
14700 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61  TIC_MEM] mutex a
14710 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a  s long as the.**
14720 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
14730 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69  MEMSTATUS] confi
14740 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
14750 69 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68  is turned on (wh
14760 69 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20  ich.** it is by 
14770 64 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20  default) and so 
14780 74 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20  the methods are 
14790 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65  automatically se
147a0 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77  rialized..** How
147b0 65 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45  ever, if [SQLITE
147c0 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55  _CONFIG_MEMSTATU
147d0 53 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20  S] is disabled, 
147e0 74 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a  then the other.*
147f0 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62  * methods must b
14800 65 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20  e threadsafe or 
14810 65 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20  else make their 
14820 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73  own arrangements
14830 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a   for.** serializ
14840 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ation..**.** SQL
14850 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69  ite will never i
14860 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f  nvoke xInit() mo
14870 72 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74  re than once wit
14880 68 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e  hout an interven
14890 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78  ing.** call to x
148a0 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74  Shutdown()..*/.t
148b0 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
148c0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
148d0 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  s sqlite3_mem_me
148e0 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
148f0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
14900 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d  s {.  void *(*xM
14910 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20  alloc)(int);    
14920 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61       /* Memory a
14930 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69  llocation functi
14940 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  on */.  void (*x
14950 46 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Free)(void*);   
14960 20 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61         /* Free a
14970 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
14980 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78  n */.  void *(*x
14990 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69  Realloc)(void*,i
149a0 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20  nt);  /* Resize 
149b0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f  an allocation */
149c0 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28  .  int (*xSize)(
149d0 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20  void*);         
149e0 20 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20    /* Return the 
149f0 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63  size of an alloc
14a00 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28  ation */.  int (
14a10 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b  *xRoundup)(int);
14a20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75            /* Rou
14a30 6e 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69  nd up request si
14a40 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze to allocation
14a50 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28   size */.  int (
14a60 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20  *xInit)(void*); 
14a70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69            /* Ini
14a80 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
14a90 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
14aa0 20 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f    void (*xShutdo
14ab0 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  wn)(void*);     
14ac0 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65   /* Deinitialize
14ad0 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
14ae0 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20  cator */.  void 
14af0 2a 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20  *pAppData;      
14b00 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67            /* Arg
14b10 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29  ument to xInit()
14b20 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29   and xShutdown()
14b30 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.};../*.** CA
14b40 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
14b50 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a  ation Options.**
14b60 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66   KEYWORDS: {conf
14b70 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
14b80 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
14b90 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20  nstants are the 
14ba0 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65  available intege
14bb0 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  r configuration 
14bc0 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20  options that.** 
14bd0 63 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73  can be passed as
14be0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
14bf0 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
14c00 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
14c10 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e  terface..**.** N
14c20 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ew configuration
14c30 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20   options may be 
14c40 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
14c50 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
14c60 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20  te..** Existing 
14c70 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14c80 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64  tions might be d
14c90 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70  iscontinued.  Ap
14ca0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68  plications.** sh
14cb0 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72  ould check the r
14cc0 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20  eturn code from 
14cd0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
14ce0 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20  )] to make sure 
14cf0 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c  that.** the call
14d00 20 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73   worked.  The [s
14d10 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14d20 20 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20   interface will 
14d30 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d  return a.** non-
14d40 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
14d50 5d 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e  ] if a discontin
14d60 75 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74  ued or unsupport
14d70 65 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ed configuration
14d80 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e   option.** is in
14d90 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  voked..**.** <dl
14da0 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  >.** [[SQLITE_CO
14db0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
14dc0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
14dd0 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
14de0 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  AD</dt>.** <dd>T
14df0 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75  here are no argu
14e00 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
14e10 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74  tion.  ^This opt
14e20 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
14e30 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
14e40 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   to Single-threa
14e50 64 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  d.  In other wor
14e60 64 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a  ds, it disables.
14e70 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20  ** all mutexing 
14e80 61 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20  and puts SQLite 
14e90 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72  into a mode wher
14ea0 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65  e it can only be
14eb0 20 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69   used.** by a si
14ec0 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e  ngle thread.   ^
14ed0 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
14ee0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
14ef0 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
14f00 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
14f10 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
14f20 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
14f30 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
14f40 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68  t possible to ch
14f50 61 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64  ange the [thread
14f60 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69  ing mode] from i
14f70 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61  ts default.** va
14f80 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68  lue of Single-th
14f90 72 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c  read and so [sql
14fa0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
14fb0 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b  ill return .** [
14fc0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
14fd0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
14fe0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
14ff0 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63  INGLETHREAD.** c
15000 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
15010 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
15020 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15030 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64  MULTITHREAD]] <d
15040 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
15050 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e  MULTITHREAD</dt>
15060 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72  .** <dd>There ar
15070 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74  e no arguments t
15080 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20  o this option.  
15090 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  ^This option set
150a0 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64  s the.** [thread
150b0 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c  ing mode] to Mul
150c0 74 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f  ti-thread.  In o
150d0 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64  ther words, it d
150e0 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78  isables.** mutex
150f0 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  ing on [database
15100 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
15110 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
15120 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
15130 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
15140 6e 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  n is responsible
15150 20 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67   for serializing
15160 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64   access to.** [d
15170 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15180 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ons] and [prepar
15190 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20  ed statements]. 
151a0 20 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78   But other mutex
151b0 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65  es.** are enable
151c0 64 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65  d so that SQLite
151d0 20 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f   will be safe to
151e0 20 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d   use in a multi-
151f0 74 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69  threaded.** envi
15200 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20  ronment as long 
15210 61 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64  as no two thread
15220 73 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65  s attempt to use
15230 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61   the same.** [da
15240 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15250 6e 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  n] at the same t
15260 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65  ime.  ^If SQLite
15270 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
15280 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
15290 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
152a0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
152b0 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
152c0 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69  option then.** i
152d0 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c  t is not possibl
152e0 65 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c  e to set the Mul
152f0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
15300 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a  ding mode] and.*
15310 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
15320 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
15330 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
15340 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74  if called with t
15350 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e  he.** SQLITE_CON
15360 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
15370 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15380 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  tion.</dd>.**.**
15390 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
153a0 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64  _SERIALIZED]] <d
153b0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
153c0 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a  SERIALIZED</dt>.
153d0 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
153e0 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
153f0 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
15400 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
15410 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
15420 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69  ng mode] to Seri
15430 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72  alized. In other
15440 20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74   words, this opt
15450 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61  ion enables.** a
15460 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75  ll mutexes inclu
15470 64 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69  ding the recursi
15480 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e  ve.** mutexes on
15490 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
154a0 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70  ction] and [prep
154b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
154c0 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74  objects..** In t
154d0 68 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20  his mode (which 
154e0 69 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77  is the default w
154f0 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
15500 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b  mpiled with.** [
15510 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
15520 45 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65  E=1]) the SQLite
15530 20 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74   library will it
15540 73 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61  self serialize a
15550 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74  ccess.** to [dat
15560 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15570 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
15580 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20   statements] so 
15590 74 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c  that the.** appl
155a0 69 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20  ication is free 
155b0 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20  to use the same 
155c0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
155d0 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20  tion] or the.** 
155e0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
155f0 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66  tatement] in dif
15600 66 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61  ferent threads a
15610 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e  t the same time.
15620 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .** ^If SQLite i
15630 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
15640 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
15650 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
15660 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
15670 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
15680 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
15690 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
156a0 74 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61  to set the Seria
156b0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
156c0 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73   mode] and.** [s
156d0 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
156e0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51   will return [SQ
156f0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
15700 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  alled with the.*
15710 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  * SQLITE_CONFIG_
15720 53 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69  SERIALIZED confi
15730 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
15740 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15750 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
15760 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
15770 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
15780 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
15790 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
157a0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
157b0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
157c0 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
157d0 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
157e0 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
157f0 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
15800 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
15810 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
15820 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
15830 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15840 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
15850 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
15860 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
15870 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
15880 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
15890 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
158a0 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
158b0 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
158c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
158d0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
158e0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
158f0 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
15900 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
15910 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
15920 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
15930 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15940 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51  TMALLOC]] <dt>SQ
15950 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15960 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ALLOC</dt>.** <d
15970 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
15980 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
15990 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
159a0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
159b0 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66  n.** instance of
159c0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65   the [sqlite3_me
159d0 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63  m_methods] struc
159e0 74 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69  ture.  The [sqli
159f0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
15a00 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
15a10 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
15a20 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
15a30 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ed memory alloca
15a40 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e  tion routines.)^
15a50 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20  .** This option 
15a60 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
15a70 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61  verload the defa
15a80 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
15a90 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65  ation.** routine
15aa0 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72  s with a wrapper
15ab0 20 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e   that simulation
15ac0 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  s memory allocat
15ad0 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a  ion failure or.*
15ae0 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20  * tracks memory 
15af0 75 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70  usage, for examp
15b00 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  le. </dd>.**.** 
15b10 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15b20 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e  MEMSTATUS]] <dt>
15b30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
15b40 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20  MSTATUS</dt>.** 
15b50 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
15b60 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61  n takes single a
15b70 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
15b80 69 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64  int, interpreted
15b90 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61   as a .** boolea
15ba0 6e 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73  n, which enables
15bb0 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
15bc0 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d   collection of m
15bd0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
15be0 20 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e   .** statistics.
15bf0 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61   ^(When memory a
15c00 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
15c10 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65  tics are disable
15c20 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f  d, the .** follo
15c30 77 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65  wing SQLite inte
15c40 72 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f  rfaces become no
15c50 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a  n-operational:.*
15c60 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  *   <ul>.**   <l
15c70 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
15c80 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20  ry_used()].**   
15c90 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65  <li> [sqlite3_me
15ca0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
15cb0 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
15cc0 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
15cd0 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c  imit64()].**   <
15ce0 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61  li> [sqlite3_sta
15cf0 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c  tus()].**   </ul
15d00 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61  >)^.** ^Memory a
15d10 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73  llocation statis
15d20 74 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64  tics are enabled
15d30 20 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65   by default unle
15d40 73 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  ss SQLite is.** 
15d50 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53  compiled with [S
15d60 51 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45  QLITE_DEFAULT_ME
15d70 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68  MSTATUS]=0 in wh
15d80 69 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a  ich case memory.
15d90 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74  ** allocation st
15da0 61 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73  atistics are dis
15db0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
15dc0 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ..** </dd>.**.**
15dd0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
15de0 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53  _SCRATCH]] <dt>S
15df0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52  QLITE_CONFIG_SCR
15e00 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATCH</dt>.** <dd
15e10 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73  > ^This option s
15e20 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69  pecifies a stati
15e30 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  c memory buffer 
15e40 74 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20  that SQLite can 
15e50 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74  use for.** scrat
15e60 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72  ch memory.  Ther
15e70 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
15e80 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65  ments:  A pointe
15e90 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61  r an 8-byte.** a
15ea0 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75  ligned memory bu
15eb0 66 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20  ffer from which 
15ec0 74 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f  the scratch allo
15ed0 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a  cations will be.
15ee0 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69  ** drawn, the si
15ef0 7a 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74  ze of each scrat
15f00 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73  ch allocation (s
15f10 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d  z),.** and the m
15f20 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
15f30 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
15f40 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73  ions (N).  The s
15f50 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75  z.** argument mu
15f60 73 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65  st be a multiple
15f70 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66   of 16..** The f
15f80 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
15f90 73 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  st be a pointer 
15fa0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69  to an 8-byte ali
15fb0 67 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f  gned buffer.** o
15fc0 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20  f at least sz*N 
15fd0 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e  bytes of memory.
15fe0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c  .** ^SQLite will
15ff0 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61   use no more tha
16000 6e 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75  n two scratch bu
16010 66 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64  ffers per thread
16020 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c  .  So.** N shoul
16030 64 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63  d be set to twic
16040 65 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d  e the expected m
16050 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
16060 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51   threads..** ^SQ
16070 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  Lite will never 
16080 72 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63  require a scratc
16090 68 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73  h buffer that is
160a0 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20   more than 6.** 
160b0 74 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61  times the databa
160c0 73 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49  se page size. ^I
160d0 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e  f SQLite needs n
160e0 65 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a  eeds additional.
160f0 2a 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72  ** scratch memor
16100 79 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73  y beyond what is
16110 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69   provided by thi
16120 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  s configuration 
16130 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a  option, then .**
16140 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
16150 28 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64  ()] will be used
16160 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d   to obtain the m
16170 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64  emory needed.</d
16180 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16190 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
161a0 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  HE]] <dt>SQLITE_
161b0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
161c0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
161d0 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69  his option speci
161e0 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65  fies a static me
161f0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74  mory buffer that
16200 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20   SQLite can use 
16210 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  for.** the datab
16220 61 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77  ase page cache w
16230 69 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20  ith the default 
16240 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
16250 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20  mentation.  .** 
16260 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  This configurati
16270 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  on should not be
16280 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c   used if an appl
16290 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70  ication-define p
162a0 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70  age.** cache imp
162b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c  lementation is l
162c0 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20  oaded using the 
162d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
162e0 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  ACHE2 option..**
162f0 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
16300 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
16310 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
16320 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
16330 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
16340 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
16350 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
16360 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
16370 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
16380 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
16390 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
163a0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
163b0 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
163c0 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
163d0 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
163e0 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
163f0 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
16400 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
16410 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
16420 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
16430 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
16440 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
16450 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
16460 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
16470 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
16480 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
16490 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
164a0 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
164b0 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
164c0 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
164d0 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
164e0 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
164f0 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
16500 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
16510 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
16520 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
16530 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
16540 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
16550 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
16560 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
16570 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
16580 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
16590 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
165a0 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
165b0 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
165c0 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
165d0 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
165e0 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
165f0 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
16600 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
16610 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
16620 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
16630 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
16640 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
16650 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
16660 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
16670 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
16680 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
16690 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
166a0 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
166b0 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
166c0 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
166d0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
166e0 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c  G_HEAP]] <dt>SQL
166f0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c  ITE_CONFIG_HEAP<
16700 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
16710 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
16720 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
16730 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
16740 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
16750 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  ** for all of it
16760 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79  s dynamic memory
16770 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
16780 73 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70  s beyond those p
16790 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62  rovided.** for b
167a0 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  y [SQLITE_CONFIG
167b0 5f 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53  _SCRATCH] and [S
167c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
167d0 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72  ECACHE]..** Ther
167e0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
167f0 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65  ments: An 8-byte
16800 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72   aligned pointer
16810 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a   to the memory,.
16820 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
16830 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65   bytes in the me
16840 6d 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64  mory buffer, and
16850 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
16860 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a  ocation size..**
16870 20 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70   ^If the first p
16880 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f  ointer (the memo
16890 72 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e  ry pointer) is N
168a0 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65  ULL, then SQLite
168b0 20 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75   reverts.** to u
168c0 73 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74  sing its default
168d0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
168e0 72 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61  r (the system ma
168f0 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74  lloc() implement
16900 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69  ation),.** undoi
16910 6e 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76  ng any prior inv
16920 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49  ocation of [SQLI
16930 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
16940 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d  ].  ^If the.** m
16950 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73  emory pointer is
16960 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69   not NULL and ei
16970 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41  ther [SQLITE_ENA
16980 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a  BLE_MEMSYS3] or.
16990 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
169a0 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64  E_MEMSYS5] are d
169b0 65 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65  efined, then the
169c0 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d   alternative mem
169d0 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
169e0 20 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68   is engaged to h
169f0 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c  andle all of SQL
16a00 69 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ites memory allo
16a10 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a  cation needs..**
16a20 20 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74   The first point
16a30 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70  er (the memory p
16a40 6f 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20  ointer) must be 
16a50 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
16a60 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79  byte.** boundary
16a70 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62   or subsequent b
16a80 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
16a90 65 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  e will be undefi
16aa0 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69  ned..** The mini
16ab0 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  mum allocation s
16ac0 69 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74  ize is capped at
16ad0 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62   2**12. Reasonab
16ae0 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72  le values.** for
16af0 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   the minimum all
16b00 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65  ocation size are
16b10 20 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a   2**5 through 2*
16b20 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  *8.</dd>.**.** [
16b30 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
16b40 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
16b50 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f  E_CONFIG_MUTEX</
16b60 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
16b70 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
16b80 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
16b90 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
16ba0 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
16bb0 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
16bc0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
16bd0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
16be0 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
16bf0 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
16c00 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
16c10 6c 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  l mutex routines
16c20 20 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70   to be used in p
16c30 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65  lace.** the mute
16c40 78 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74  x routines built
16c50 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20   into SQLite.)^ 
16c60 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
16c70 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
16c80 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
16c90 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
16ca0 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
16cb0 20 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c   before the call
16cc0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
16cd0 63 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e  config()] return
16ce0 73 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  s. ^If SQLite is
16cf0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
16d00 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
16d10 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
16d20 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
16d30 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
16d40 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ion then.** the 
16d50 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20  entire mutexing 
16d60 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69  subsystem is omi
16d70 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75  tted from the bu
16d80 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61  ild and hence ca
16d90 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  lls to.** [sqlit
16da0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74  e3_config()] wit
16db0 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  h the SQLITE_CON
16dc0 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67  FIG_MUTEX config
16dd0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77  uration option w
16de0 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  ill.** return [S
16df0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64  QLITE_ERROR].</d
16e00 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
16e10 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
16e20 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  X]] <dt>SQLITE_C
16e30 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f  ONFIG_GETMUTEX</
16e40 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
16e50 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
16e60 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
16e70 74 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69  t which is a poi
16e80 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e  nter to an.** in
16e90 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73  stance of the [s
16ea0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
16eb0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
16ec0 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    The.** [sqlite
16ed0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
16ee0 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73  .** structure is
16ef0 20 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65   filled with the
16f00 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e   currently defin
16f10 65 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65  ed mutex routine
16f20 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
16f30 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
16f40 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
16f50 64 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c  default mutex al
16f60 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
16f70 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
16f80 70 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63  per used to trac
16f90 6b 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f  k mutex usage fo
16fa0 72 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a  r performance.**
16fb0 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65   profiling or te
16fc0 73 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70  sting, for examp
16fd0 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65  le.   ^If SQLite
16fe0 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
16ff0 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
17000 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
17010 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
17020 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
17030 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
17040 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
17050 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
17060 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
17070 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
17080 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
17090 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
170a0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
170b0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
170c0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
170d0 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
170e0 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
170f0 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
17100 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
17110 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53  OOKASIDE]] <dt>S
17120 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17130 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  KASIDE</dt>.** <
17140 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
17150 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
17160 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72  ments that deter
17170 6d 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74  mine the default
17180 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  .** memory alloc
17190 61 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f  ation for the lo
171a0 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
171b0 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68  llocator on each
171c0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
171d0 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20  nnection].  The 
171e0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
171f0 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66  s the.** size of
17200 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20   each lookaside 
17210 62 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20  buffer slot and 
17220 74 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68  the second is th
17230 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73  e number of.** s
17240 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74  lots allocated t
17250 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
17260 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e  connection.)^  ^
17270 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74  (This option set
17280 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61  s the.** <i>defa
17290 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64  ult</i> lookasid
172a0 65 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c  e size. The [SQL
172b0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
172c0 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20  KASIDE].** verb 
172d0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
172e0 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20  onfig()] can be 
172f0 75 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74  used to change t
17300 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20  he lookaside.** 
17310 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e  configuration on
17320 20 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e   individual conn
17330 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e  ections.)^ </dd>
17340 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17350 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d  CONFIG_PCACHE2]]
17360 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17370 49 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  IG_PCACHE2</dt>.
17380 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
17390 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
173a0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
173b0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
173c0 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74   to.** an [sqlit
173d0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
173e0 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69  s2] object.  Thi
173f0 73 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69  s object specifi
17400 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
17410 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20  .** to a custom 
17420 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
17430 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53  mentation.)^  ^S
17440 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
17450 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a  py of the.** obj
17460 65 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20  ect and uses it 
17470 66 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d  for page cache m
17480 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
17490 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  s.</dd>.**.** [[
174a0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
174b0 54 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53  TPCACHE2]] <dt>S
174c0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
174d0 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20  PCACHE2</dt>.** 
174e0 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69  <dd> ^(This opti
174f0 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c  on takes a singl
17500 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  e argument which
17510 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
17520 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
17530 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d  pcache_methods2]
17540 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65   object.  SQLite
17550 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63   copies of the c
17560 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63  urrent.** page c
17570 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ache implementat
17580 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62  ion into that ob
17590 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a  ject.)^ </dd>.**
175a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
175b0 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51  FIG_LOG]] <dt>SQ
175c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c  LITE_CONFIG_LOG<
175d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
175e0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
175f0 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  LOG option takes
17600 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20   two arguments: 
17610 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a  a pointer to a.*
17620 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20  * function with 
17630 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65  a call signature
17640 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   of void(*)(void
17650 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
17660 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f  *), .** and a po
17670 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e  inter to void. ^
17680 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
17690 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e  pointer is not N
176a0 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e  ULL, it is.** in
176b0 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65  voked by [sqlite
176c0 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63  3_log()] to proc
176d0 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67  ess each logging
176e0 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
176f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69  .** function poi
17700 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68  nter is NULL, th
17710 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29  e [sqlite3_log()
17720 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f  ] interface beco
17730 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20  mes a no-op..** 
17740 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65  ^The void pointe
17750 72 20 74 68 61 74 20 69 73 20 74 68 65 20 73 65  r that is the se
17760 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
17770 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c   SQLITE_CONFIG_L
17780 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20  OG is.** passed 
17790 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
177a0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
177b0 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
177c0 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72  n-defined logger
177d0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  .** function whe
177e0 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e 63 74  never that funct
177f0 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ion is invoked. 
17800 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
17810 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65  ameter to.** the
17820 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e   logger function
17830 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
17840 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
17850 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70  r to the corresp
17860 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74  onding.** [sqlit
17870 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61  e3_log()] call a
17880 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  nd is intended t
17890 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63  o be a [result c
178a0 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  ode] or an.** [e
178b0 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
178c0 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72  ode].  ^The thir
178d0 64 20 70 61 72 61 6d 65 74 65 72 20 70 61 73 73  d parameter pass
178e0 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72  ed to the logger
178f0 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61   is.** log messa
17900 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74  ge after formatt
17910 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33  ing via [sqlite3
17920 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a  _snprintf()]..**
17930 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67   The SQLite logg
17940 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20 69 73  ing interface is
17950 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20   not reentrant; 
17960 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
17970 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20  ion.** supplied 
17980 62 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  by the applicati
17990 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f  on must not invo
179a0 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e  ke any SQLite in
179b0 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61  terface..** In a
179c0 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20   multi-threaded 
179d0 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65  application, the
179e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
179f0 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66  ined logger.** f
17a00 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  unction must be 
17a10 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64  threadsafe. </dd
17a20 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
17a30 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64  _CONFIG_URI]] <d
17a40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
17a50 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73  URI.** <dd> This
17a60 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
17a70 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
17a80 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
17a90 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
17aa0 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
17ab0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
17ac0 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
17ad0 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
17ae0 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
17af0 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
17b00 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20  isabled. If URI 
17b10 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
17b20 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c  ally enabled, al
17b30 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70  l filenames.** p
17b40 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
17b50 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
17b60 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
17b70 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
17b80 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
17b90 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
17ba0 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
17bb0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
17bc0 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
17bd0 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
17be0 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
17bf0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
17c00 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
17c10 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
17c20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
17c30 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67  ened. If it is g
17c40 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
17c50 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
17c60 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
17c70 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
17c80 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
17c90 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
17ca0 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
17cb0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
17cc0 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66  s opened. By def
17cd0 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
17ce0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
17cf0 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
17d00 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
17d10 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
17d20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
17d30 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
17d40 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
17d50 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  fined..**.** [[S
17d60 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
17d70 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
17d80 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
17d90 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
17da0 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
17db0 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
17dc0 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
17dd0 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
17de0 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
17df0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
17e00 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
17e10 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
17e20 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
17e30 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
17e40 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
17e50 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  -ops..** </dl>.*
17e60 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
17e70 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
17e80 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20  READ  1  /* nil 
17e90 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
17ea0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
17eb0 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c  READ   2  /* nil
17ec0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
17ed0 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c  TE_CONFIG_SERIAL
17ee0 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69  IZED    3  /* ni
17ef0 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
17f00 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
17f10 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73  C        4  /* s
17f20 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
17f30 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ds* */.#define S
17f40 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
17f50 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a  MALLOC     5  /*
17f60 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
17f70 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  hods* */.#define
17f80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
17f90 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20  CRATCH       6  
17fa0 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a  /* void*, int sz
17fb0 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69  , int N */.#defi
17fc0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
17fd0 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37  _PAGECACHE     7
17fe0 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20    /* void*, int 
17ff0 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65  sz, int N */.#de
18000 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18010 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20  IG_HEAP         
18020 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   8  /* void*, in
18030 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e  t nByte, int min
18040 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18050 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
18060 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f  TUS     9  /* bo
18070 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65  olean */.#define
18080 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
18090 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20  UTEX        10  
180a0 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  /* sqlite3_mutex
180b0 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
180c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
180d0 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20  IG_GETMUTEX     
180e0 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  11  /* sqlite3_m
180f0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
18100 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53  ./* previously S
18110 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55  QLITE_CONFIG_CHU
18120 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68  NKALLOC 12 which
18130 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20   is now unused. 
18140 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  */ .#define SQLI
18150 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
18160 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e  IDE    13  /* in
18170 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  t int */.#define
18180 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
18190 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20  CACHE       14  
181a0 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66  /* no-op */.#def
181b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
181c0 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31  G_GETPCACHE    1
181d0 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  5  /* no-op */.#
181e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
181f0 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20  NFIG_LOG        
18200 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20    16  /* xFunc, 
18210 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
18220 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55   SQLITE_CONFIG_U
18230 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20  RI          17  
18240 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  /* int */.#defin
18250 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18260 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20  PCACHE2      18 
18270 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
18280 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a  he_methods2* */.
18290 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
182a0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32  ONFIG_GETPCACHE2
182b0 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65     19  /* sqlite
182c0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
182d0 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  2* */../*.** CAP
182e0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
182f0 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
18300 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
18310 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
18320 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
18330 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
18340 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
18350 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
18360 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
18370 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
18380 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
18390 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
183a0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
183b0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
183c0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
183d0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
183e0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
183f0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
18400 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
18410 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
18420 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
18430 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
18440 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
18450 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
18460 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
18470 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
18480 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
18490 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
184a0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
184b0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
184c0 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
184d0 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
184e0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
184f0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
18500 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
18510 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
18520 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
18530 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
18540 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
18550 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
18560 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
18570 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
18580 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
18590 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
185a0 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
185b0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
185c0 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
185d0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
185e0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
185f0 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
18600 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
18610 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
18620 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
18630 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
18640 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
18650 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
18660 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
18670 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
18680 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
18690 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
186a0 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
186b0 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
186c0 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
186d0 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
186e0 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
186f0 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
18700 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
18710 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
18720 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
18730 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
18740 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
18750 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
18760 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
18770 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
18780 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
18790 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
187a0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
187b0 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
187c0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
187d0 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
187e0 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
187f0 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
18800 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
18810 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
18820 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
18830 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
18840 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
18850 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
18860 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
18870 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
18880 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
18890 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
188a0 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
188b0 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
188c0 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
188d0 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
188e0 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
188f0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
18900 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
18910 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
18920 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
18930 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
18940 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
18950 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
18960 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
18970 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
18980 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
18990 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
189a0 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
189b0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
189c0 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
189d0 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
189e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
189f0 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
18a00 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
18a10 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
18a20 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
18a30 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
18a40 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
18a50 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
18a60 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
18a70 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
18a80 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
18a90 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
18aa0 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
18ab0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
18ac0 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
18ad0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
18ae0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
18af0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
18b00 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
18b10 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
18b20 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
18b30 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
18b40 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
18b50 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
18b60 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
18b70 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
18b80 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
18b90 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
18ba0 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
18bb0 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
18bc0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
18bd0 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
18be0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
18bf0 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
18c00 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18c10 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
18c20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
18c30 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
18c40 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
18c50 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
18c60 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
18c70 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
18c80 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
18c90 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
18ca0 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
18cb0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
18cc0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
18cd0 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
18ce0 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
18cf0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
18d00 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
18d10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
18d20 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
18d30 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
18d40 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
18d50 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
18d60 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
18d70 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
18d80 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
18d90 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
18da0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
18db0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
18dc0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
18dd0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
18de0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
18df0 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
18e00 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
18e10 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
18e20 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
18e30 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
18e40 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
18e50 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18e60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18e70 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18e80 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18e90 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18ea0 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
18eb0 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
18ec0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
18ed0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
18ee0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
18ef0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
18f00 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
18f10 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
18f20 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
18f30 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
18f40 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
18f50 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
18f60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
18f70 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
18f80 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f  DE       1001  /
18f90 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
18fa0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
18fb0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
18fc0 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20  E_FKEY     1002 
18fd0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
18fe0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
18ff0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
19000 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a  RIGGER  1003  /*
19010 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f   int int* */.../
19020 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
19030 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
19040 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
19050 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Codes.**.** ^Th
19060 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
19070 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
19080 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
19090 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
190a0 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
190b0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
190c0 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
190d0 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
190e0 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
190f0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
19100 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
19110 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
19120 74 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ty..*/.SQLITE_AP
19130 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  I int sqlite3_ex
19140 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
19150 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
19160 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
19170 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
19180 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
19190 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
191a0 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
191b0 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
191c0 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
191d0 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
191e0 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
191f0 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
19200 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
19210 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
19220 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
19230 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
19240 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
19250 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
19260 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
19270 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
19280 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
19290 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
192a0 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
192b0 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
192c0 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
192d0 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
192e0 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
192f0 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
19300 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
19310 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
19320 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
19330 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
19340 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
19350 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
19360 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
19370 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
19380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
19390 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
193a0 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f  argument.  ^As o
193b0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
193c0 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75   3.7.7, this rou
193d0 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73  tines.** records
193e0 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
193f0 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f   rowid of both o
19400 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61  rdinary tables a
19410 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  nd [virtual tabl
19420 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  es]..** ^If no s
19430 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
19440 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  T]s.** have ever
19450 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
19460 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
19470 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
19480 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
19490 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
194a0 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
194b0 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69  trigger or withi
194c0 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  n a [virtual tab
194d0 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74  le].** method, t
194e0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
194f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
19500 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
19510 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
19520 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
19530 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
19540 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69  l table method i
19550 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
19560 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
19570 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
19580 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c  ble method ends,
19590 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
195a0 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
195b0 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
195c0 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
195d0 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
195e0 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20  r or virtual.** 
195f0 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67  table method beg
19600 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  an.)^.**.** ^An 
19610 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
19620 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
19630 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
19640 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
19650 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
19660 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
19670 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
19680 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
19690 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
196a0 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
196b0 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
196c0 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
196d0 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
196e0 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
196f0 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
19700 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
19710 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
19720 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
19730 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
19740 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
19750 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
19760 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
19770 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
19780 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
19790 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
197a0 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
197b0 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
197c0 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
197d0 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
197e0 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
197f0 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
19800 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
19810 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
19820 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
19830 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
19840 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
19850 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
19860 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
19870 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
19880 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
19890 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
198a0 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
198b0 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
198c0 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
198d0 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
198e0 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
198f0 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
19900 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
19910 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
19920 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
19930 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
19940 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
19950 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
19960 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
19970 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
19980 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
19990 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
199a0 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
199b0 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
199c0 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
199d0 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
199e0 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
199f0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
19a00 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
19a10 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19a20 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
19a30 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
19a40 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
19a50 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
19a60 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
19a70 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
19a80 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  /.SQLITE_API sql
19a90 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
19aa0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
19ab0 6f 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a  owid(sqlite3*);.
19ac0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
19ad0 20 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65   Count The Numbe
19ae0 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69  r Of Rows Modifi
19af0 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ed.**.** ^This f
19b00 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
19b10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61  the number of da
19b20 74 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74  tabase rows that
19b30 20 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a   were changed.**
19b40 20 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20   or inserted or 
19b50 64 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d  deleted by the m
19b60 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d  ost recently com
19b70 70 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65  pleted SQL state
19b80 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b  ment.** on the [
19b90 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19ba0 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62  ion] specified b
19bb0 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  y the first para
19bc0 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79  meter..** ^(Only
19bd0 20 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72   changes that ar
19be0 65 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69  e directly speci
19bf0 66 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53  fied by the [INS
19c00 45 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a  ERT], [UPDATE],.
19c10 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  ** or [DELETE] s
19c20 74 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75  tatement are cou
19c30 6e 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79  nted.  Auxiliary
19c40 20 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20   changes caused 
19c50 62 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f  by.** triggers o
19c60 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  r [foreign key a
19c70 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20  ctions] are not 
19c80 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74  counted.)^ Use t
19c90 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74  he.** [sqlite3_t
19ca0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
19cb0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64  function to find
19cc0 20 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65   the total numbe
19cd0 72 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20  r of changes.** 
19ce0 69 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65  including change
19cf0 73 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67  s caused by trig
19d00 67 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e  gers and foreign
19d10 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a   key actions..**
19d20 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20  .** ^Changes to 
19d30 61 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20  a view that are 
19d40 73 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20  simulated by an 
19d50 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
19d60 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  ger].** are not 
19d70 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72  counted.  Only r
19d80 65 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65  eal table change
19d90 73 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a  s are counted..*
19da0 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68  *.** ^(A "row ch
19db0 61 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67  ange" is a chang
19dc0 65 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f  e to a single ro
19dd0 77 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61  w of a single ta
19de0 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79  ble.** caused by
19df0 20 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45   an INSERT, DELE
19e00 54 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74  TE, or UPDATE st
19e10 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74  atement.  Rows t
19e20 68 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67  hat.** are chang
19e30 65 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63  ed as side effec
19e40 74 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20  ts of [REPLACE] 
19e50 63 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c  constraint resol
19e60 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61  ution,.** rollba
19e70 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73  ck, ABORT proces
19e80 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c  sing, [DROP TABL
19e90 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74  E], or by any ot
19ea0 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d  her.** mechanism
19eb0 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
19ec0 73 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  s direct row cha
19ed0 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20  nges.)^.**.** A 
19ee0 22 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74  "trigger context
19ef0 22 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20  " is a scope of 
19f00 65 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62  execution that b
19f10 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64  egins and.** end
19f20 73 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70  s with the scrip
19f30 74 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54  t of a [CREATE T
19f40 52 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72  RIGGER | trigger
19f50 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20  ]. .** Most SQL 
19f60 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a  statements are.*
19f70 2a 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73  * evaluated outs
19f80 69 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67  ide of any trigg
19f90 65 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65  er.  This is the
19fa0 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20   "top level".** 
19fb0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
19fc0 20 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66    If a trigger f
19fd0 69 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f  ires from the to
19fe0 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65  p level, a.** ne
19ff0 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
1a000 74 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72  t is entered for
1a010 20 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66   the duration of
1a020 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69   that one.** tri
1a030 67 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65  gger.  Subtrigge
1a040 72 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e  rs create subcon
1a050 74 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20  texts for their 
1a060 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  duration..**.** 
1a070 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65  ^Calling [sqlite
1a080 33 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71  3_exec()] or [sq
1a090 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
1a0a0 63 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a  cursively does.*
1a0b0 2a 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e  * not create a n
1a0c0 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ew trigger conte
1a0d0 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  xt..**.** ^This 
1a0e0 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73  function returns
1a0f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
1a100 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
1a110 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74  s in the.** most
1a120 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
1a130 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
1a140 45 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68  E statement with
1a150 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74  in the same.** t
1a160 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a  rigger context..
1a170 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65  **.** ^Thus, whe
1a180 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  n called from th
1a190 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69  e top level, thi
1a1a0 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1a1b0 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  ns the.** number
1a1c0 20 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74   of changes in t
1a1d0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49  he most recent I
1a1e0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
1a1f0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
1a200 20 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61   also occurred a
1a210 74 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e  t the top level.
1a220 20 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62    ^(Within the b
1a230 6f 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72  ody of a trigger
1a240 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33  ,.** the sqlite3
1a250 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72  _changes() inter
1a260 66 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  face can be call
1a270 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
1a280 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e  umber of.** chan
1a290 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20  ges in the most 
1a2a0 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74  recently complet
1a2b0 65 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54  ed INSERT, UPDAT
1a2c0 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20  E, or DELETE.** 
1a2d0 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
1a2e0 20 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65   the body of the
1a2f0 20 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a   same trigger..*
1a300 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e  * However, the n
1a310 75 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64  umber returned d
1a320 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20  oes not include 
1a330 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65  changes.** cause
1a340 64 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73  d by subtriggers
1a350 20 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76   since those hav
1a360 65 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74  e their own cont
1a370 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65  ext.)^.**.** See
1a380 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74   also the [sqlit
1a390 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1a3a0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74  ()] interface, t
1a3b0 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61  he.** [count_cha
1a3c0 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e  nges pragma], an
1a3d0 64 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29  d the [changes()
1a3e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a   SQL function]..
1a3f0 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72  **.** If a separ
1a400 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73  ate thread makes
1a410 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20   changes on the 
1a420 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f  same database co
1a430 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c  nnection.** whil
1a440 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
1a450 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1a460 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
1a470 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75  returned.** is u
1a480 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1a490 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1a4a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1a4b0 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  nt sqlite3_chang
1a4c0 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  es(sqlite3*);../
1a4d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1a4e0 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52  otal Number Of R
1a4f0 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
1a500 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1a510 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
1a520 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e  mber of row chan
1a530 67 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49  ges caused by [I
1a540 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41  NSERT],.** [UPDA
1a550 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20  TE] or [DELETE] 
1a560 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65  statements since
1a570 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1a580 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f  onnection] was o
1a590 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20  pened..** ^(The 
1a5a0 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62  count returned b
1a5b0 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  y sqlite3_total_
1a5c0 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64  changes() includ
1a5d0 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a  es all changes.*
1a5e0 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41  * from all [CREA
1a5f0 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
1a600 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61  gger] contexts a
1a610 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20  nd changes made 
1a620 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  by.** [foreign k
1a630 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77  ey actions]. How
1a640 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75  ever,.** the cou
1a650 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
1a660 75 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64  ude changes used
1a670 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52   to implement [R
1a680 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69  EPLACE] constrai
1a690 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62  nts,.** do rollb
1a6a0 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72  acks or ABORT pr
1a6b0 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52  ocessing, or [DR
1a6c0 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73  OP TABLE] proces
1a6d0 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f  sing.  The.** co
1a6e0 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  unt does not inc
1a6f0 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65  lude rows of vie
1a700 77 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20  ws that fire an 
1a710 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67  [INSTEAD OF trig
1a720 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20  ger],.** though 
1a730 69 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f  if the INSTEAD O
1a740 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20  F trigger makes 
1a750 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f  changes of its o
1a760 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65  wn, those change
1a770 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65  s .** are counte
1a780 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  d.)^.** ^The sql
1a790 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1a7a0 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f  es() function co
1a7b0 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73  unts the changes
1a7c0 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74   as soon as.** t
1a7d0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  he statement tha
1a7e0 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20  t makes them is 
1a7f0 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20  completed (when 
1a800 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
1a810 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65  ndle.** is passe
1a820 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  d to [sqlite3_re
1a830 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
1a840 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e  e3_finalize()]).
1a850 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
1a860 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61  the [sqlite3_cha
1a870 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63  nges()] interfac
1a880 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74  e, the.** [count
1a890 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d  _changes pragma]
1a8a0 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c  , and the [total
1a8b0 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  _changes() SQL f
1a8c0 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
1a8d0 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
1a8e0 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
1a8f0 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
1a900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a910 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
1a920 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67  ite3_total_chang
1a930 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67  es()] is running
1a940 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a   then the value.
1a950 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75  ** returned is u
1a960 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
1a970 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e   not meaningful.
1a980 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1a990 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c  nt sqlite3_total
1a9a0 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33  _changes(sqlite3
1a9b0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1a9c0 52 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41  REF: Interrupt A
1a9d0 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75   Long-Running Qu
1a9e0 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20  ery.**.** ^This 
1a9f0 66 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20  function causes 
1aa00 61 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61  any pending data
1aa10 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74  base operation t
1aa20 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72  o abort and.** r
1aa30 65 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72  eturn at its ear
1aa40 6c 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74  liest opportunit
1aa50 79 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  y. This routine 
1aa60 69 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20  is typically.** 
1aa70 63 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e  called in respon
1aa80 73 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74  se to a user act
1aa90 69 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73  ion such as pres
1aaa0 73 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a  sing "Cancel".**
1aab0 20 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65   or Ctrl-C where
1aac0 20 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20   the user wants 
1aad0 61 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65  a long query ope
1aae0 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a  ration to halt.*
1aaf0 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  * immediately..*
1ab00 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65  *.** ^It is safe
1ab10 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
1ab20 75 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72  utine from a thr
1ab30 65 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72  ead different fr
1ab40 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64  om the.** thread
1ab50 20 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74   that is current
1ab60 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64  ly running the d
1ab70 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
1ab80 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73  n.  But it.** is
1ab90 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c   not safe to cal
1aba0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  l this routine w
1abb0 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
1abc0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
1abd0 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72  .** is closed or
1abe0 20 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66   might close bef
1abf0 6f 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  ore sqlite3_inte
1ac00 72 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e  rrupt() returns.
1ac10 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51  .**.** ^If an SQ
1ac20 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76  L operation is v
1ac30 65 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73  ery nearly finis
1ac40 68 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20  hed at the time 
1ac50 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  when.** sqlite3_
1ac60 69 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63  interrupt() is c
1ac70 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d  alled, then it m
1ac80 69 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e  ight not have an
1ac90 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20   opportunity.** 
1aca0 74 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65  to be interrupte
1acb0 64 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74  d and might cont
1acc0 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69  inue to completi
1acd0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51  on..**.** ^An SQ
1ace0 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74  L operation that
1acf0 20 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20   is interrupted 
1ad00 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
1ad10 49 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a  ITE_INTERRUPT]..
1ad20 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72  ** ^If the inter
1ad30 72 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61  rupted SQL opera
1ad40 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52  tion is an INSER
1ad50 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
1ad60 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20  LETE.** that is 
1ad70 69 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63  inside an explic
1ad80 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  it transaction, 
1ad90 74 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20  then the entire 
1ada0 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77  transaction.** w
1adb0 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ill be rolled ba
1adc0 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
1add0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1ade0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
1adf0 29 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66  ) call is in eff
1ae00 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75  ect until all cu
1ae10 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a  rrently running.
1ae20 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1ae30 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  s on [database c
1ae40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d  onnection] D com
1ae50 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77  plete.  ^Any new
1ae60 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1ae70 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72  ** that are star
1ae80 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71  ted after the sq
1ae90 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
1aea0 29 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72  ) call and befor
1aeb0 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e  e the .** runnin
1aec0 67 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61  g statements rea
1aed0 63 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e  ches zero are in
1aee0 74 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20  terrupted as if 
1aef0 74 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a  they had been.**
1af00 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74   running prior t
1af10 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  o the sqlite3_in
1af20 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20  terrupt() call. 
1af30 20 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d   ^New SQL statem
1af40 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
1af50 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
1af60 68 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  he running state
1af70 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68  ment count reach
1af80 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e  es zero are.** n
1af90 6f 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74  ot effected by t
1afa0 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
1afb0 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61  rupt()..** ^A ca
1afc0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e  ll to sqlite3_in
1afd0 74 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20  terrupt(D) that 
1afe0 6f 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72  occurs when ther
1aff0 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67  e are no running
1b000 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
1b010 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e  ts is a no-op an
1b020 64 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20  d has no effect 
1b030 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  on SQL statement
1b040 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
1b050 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
1b060 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1b070 74 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  t() call returns
1b080 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64  ..**.** If the d
1b090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b0a0 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20  on closes while 
1b0b0 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75  [sqlite3_interru
1b0c0 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e  pt()].** is runn
1b0d0 69 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69  ing then bad thi
1b0e0 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ngs will likely 
1b0f0 68 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54  happen..*/.SQLIT
1b100 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
1b110 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c  e3_interrupt(sql
1b120 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
1b130 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
1b140 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
1b150 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65  tement Is Comple
1b160 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  te.**.** These r
1b170 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66  outines are usef
1b180 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e  ul during comman
1b190 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20  d-line input to 
1b1a0 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65  determine if the
1b1b0 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e  .** currently en
1b1c0 74 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73  tered text seems
1b1d0 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c   to form a compl
1b1e0 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1b1f0 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74  t or.** if addit
1b200 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e  ional input is n
1b210 65 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e  eeded before sen
1b220 64 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e  ding the text in
1b230 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72  to.** SQLite for
1b240 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73   parsing.  ^Thes
1b250 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1b260 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74  n 1 if the input
1b270 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61   string.** appea
1b280 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c  rs to be a compl
1b290 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ete SQL statemen
1b2a0 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74  t.  ^A statement
1b2b0 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65   is judged to be
1b2c0 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20  .** complete if 
1b2d0 69 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73  it ends with a s
1b2e0 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61  emicolon token a
1b2f0 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66  nd is not a pref
1b300 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d  ix of a.** well-
1b310 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52  formed CREATE TR
1b320 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e  IGGER statement.
1b330 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68    ^Semicolons th
1b340 61 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20  at are embedded 
1b350 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67  within.** string
1b360 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f   literals or quo
1b370 74 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e  ted identifier n
1b380 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73  ames or comments
1b390 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65   are not.** inde
1b3a0 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28  pendent tokens (
1b3b0 74 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66  they are part of
1b3c0 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68   the token in wh
1b3d0 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20  ich they are.** 
1b3e0 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68  embedded) and th
1b3f0 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20  us do not count 
1b400 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74  as a statement t
1b410 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69  erminator.  ^Whi
1b420 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63  tespace.** and c
1b430 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c  omments that fol
1b440 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65  low the final se
1b450 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f  micolon are igno
1b460 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  red..**.** ^Thes
1b470 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  e routines retur
1b480 6e 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65  n 0 if the state
1b490 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65  ment is incomple
1b4a0 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65  te.  ^If a.** me
1b4b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
1b4c0 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49  fails, then SQLI
1b4d0 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75  TE_NOMEM is retu
1b4e0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rned..**.** ^The
1b4f0 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e  se routines do n
1b500 6f 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c  ot parse the SQL
1b510 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73   statements thus
1b520 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74  .** will not det
1b530 65 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c  ect syntacticall
1b540 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e  y incorrect SQL.
1b550 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69  .**.** ^(If SQLi
1b560 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  te has not been 
1b570 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e  initialized usin
1b580 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  g [sqlite3_initi
1b590 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a  alize()] prior .
1b5a0 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73  ** to invoking s
1b5b0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1b5c0 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33  6() then sqlite3
1b5d0 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
1b5e0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f   invoked.** auto
1b5f0 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
1b600 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
1b610 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74  ).  If that init
1b620 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73  ialization fails
1b630 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65  ,.** then the re
1b640 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20  turn value from 
1b650 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1b660 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e  16() will be non
1b670 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c  -zero.** regardl
1b680 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1b690 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20  r not the input 
1b6a0 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e  SQL is complete.
1b6b0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70  )^.**.** The inp
1b6c0 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ut to [sqlite3_c
1b6d0 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20  omplete()] must 
1b6e0 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  be a zero-termin
1b6f0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74  ated.** UTF-8 st
1b700 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
1b710 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
1b720 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20  3_complete16()] 
1b730 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74  must be a zero-t
1b740 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46  erminated.** UTF
1b750 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61  -16 string in na
1b760 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
1b770 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1b780 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
1b790 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a  ete(const char *
1b7a0 73 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  sql);.SQLITE_API
1b7b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d   int sqlite3_com
1b7c0 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f  plete16(const vo
1b7d0 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a  id *sql);../*.**
1b7e0 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
1b7f0 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54  ter A Callback T
1b800 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f  o Handle SQLITE_
1b810 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a  BUSY Errors.**.*
1b820 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1b830 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  sets a callback 
1b840 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69  function that mi
1b850 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77  ght be invoked w
1b860 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74  henever.** an at
1b870 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f  tempt is made to
1b880 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65   open a database
1b890 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74   table that anot
1b8a0 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
1b8b0 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63   process has loc
1b8c0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ked..**.** ^If t
1b8d0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
1b8e0 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b   is NULL, then [
1b8f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
1b900 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
1b910 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74  OCKED].** is ret
1b920 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  urned immediatel
1b930 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72  y upon encounter
1b940 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e  ing the lock.  ^
1b950 49 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c  If the busy call
1b960 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e  back.** is not N
1b970 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61  ULL, then the ca
1b980 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20  llback might be 
1b990 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f  invoked with two
1b9a0 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a   arguments..**.*
1b9b0 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67  * ^The first arg
1b9c0 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73  ument to the bus
1b9d0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63  y handler is a c
1b9e0 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a  opy of the void*
1b9f0 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a   pointer which.*
1ba00 2a 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61  * is the third a
1ba10 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
1ba20 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1ba30 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ).  ^The second 
1ba40 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74  argument to.** t
1ba50 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
1ba60 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20  callback is the 
1ba70 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20  number of times 
1ba80 74 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61  that the busy ha
1ba90 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65  ndler has.** bee
1baa0 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68  n invoked for th
1bab0 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74  is locking event
1bac0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75  .  ^If the.** bu
1bad0 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  sy callback retu
1bae0 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61  rns 0, then no a
1baf0 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70  dditional attemp
1bb00 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a  ts are made to.*
1bb10 2a 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  * access the dat
1bb20 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54  abase and [SQLIT
1bb30 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49  E_BUSY] or [SQLI
1bb40 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
1bb50 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  ] is returned..*
1bb60 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61  * ^If the callba
1bb70 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1bb80 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65  ero, then anothe
1bb90 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20  r attempt.** is 
1bba0 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  made to open the
1bbb0 20 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65   database for re
1bbc0 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79  ading and the cy
1bbd0 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a  cle repeats..**.
1bbe0 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20  ** The presence 
1bbf0 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65  of a busy handle
1bc00 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61  r does not guara
1bc10 6e 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c  ntee that it wil
1bc20 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  l be invoked.** 
1bc30 77 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f  when there is lo
1bc40 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e  ck contention. ^
1bc50 49 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d  If SQLite determ
1bc60 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69  ines that invoki
1bc70 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68  ng the busy.** h
1bc80 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73  andler could res
1bc90 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63  ult in a deadloc
1bca0 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68  k, it will go ah
1bcb0 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  ead and return [
1bcc0 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20  SQLITE_BUSY].** 
1bcd0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
1bce0 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61  _BLOCKED] instea
1bcf0 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68  d of invoking th
1bd00 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a  e busy handler..
1bd10 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63  ** Consider a sc
1bd20 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65  enario where one
1bd30 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
1bd40 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20  ing a read lock 
1bd50 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72  that.** it is tr
1bd60 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20  ying to promote 
1bd70 74 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f  to a reserved lo
1bd80 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f  ck and.** a seco
1bd90 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  nd process is ho
1bda0 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64  lding a reserved
1bdb0 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73   lock that it is
1bdc0 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72   trying.** to pr
1bdd0 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c  omote to an excl
1bde0 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65  usive lock.  The
1bdf0 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63   first process c
1be00 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a  annot proceed.**
1be10 20 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62   because it is b
1be20 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65  locked by the se
1be30 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63  cond and the sec
1be40 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e  ond process cann
1be50 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65  ot.** proceed be
1be60 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63  cause it is bloc
1be70 6b 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ked by the first
1be80 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65  .  If both proce
1be90 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74  sses.** invoke t
1bea0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  he busy handlers
1beb0 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d  , neither will m
1bec0 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73  ake any progress
1bed0 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a  .  Therefore,.**
1bee0 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20   SQLite returns 
1bef0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f  [SQLITE_BUSY] fo
1bf00 72 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63  r the first proc
1bf10 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74  ess, hoping that
1bf20 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e   this.** will in
1bf30 64 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70  duce the first p
1bf40 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73  rocess to releas
1bf50 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20  e its read lock 
1bf60 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65  and allow.** the
1bf70 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20   second process 
1bf80 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a  to proceed..**.*
1bf90 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62  * ^The default b
1bfa0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
1bfb0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
1bfc0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65   [SQLITE_BUSY] e
1bfd0 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65  rror is converte
1bfe0 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45  d to [SQLITE_IOE
1bff0 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77  RR_BLOCKED].** w
1c000 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e  hen SQLite is in
1c010 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61   the middle of a
1c020 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69   large transacti
1c030 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65  on where all the
1c040 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c  .** changes will
1c050 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68   not fit into th
1c060 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68  e in-memory cach
1c070 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a  e.  SQLite will.
1c080 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20  ** already hold 
1c090 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20  a RESERVED lock 
1c0a0 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  on the database 
1c0b0 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65  file, but it nee
1c0c0 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65  ds.** to promote
1c0d0 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58   this lock to EX
1c0e0 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20  CLUSIVE so that 
1c0f0 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63  it can spill cac
1c100 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f  he.** pages into
1c110 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
1c120 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20  le without harm 
1c130 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a  to concurrent.**
1c140 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69   readers.  ^If i
1c150 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70  t is unable to p
1c160 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c  romote the lock,
1c170 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d   then the in-mem
1c180 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c  ory.** cache wil
1c190 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20  l be left in an 
1c1a0 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61  inconsistent sta
1c1b0 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72  te and so the er
1c1c0 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70  ror.** code is p
1c1d0 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65  romoted from the
1c1e0 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69   relatively beni
1c1f0 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  gn [SQLITE_BUSY]
1c200 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20   to.** the more 
1c210 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49  severe [SQLITE_I
1c220 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20  OERR_BLOCKED].  
1c230 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65  ^This error code
1c240 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f   promotion.** fo
1c250 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69  rces an automati
1c260 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68  c rollback of th
1c270 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20  e changes.  See 
1c280 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22  the.** <a href="
1c290 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d  /cvstrac/wiki?p=
1c2a0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
1c2b0 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a  ingBusyError">.*
1c2c0 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  * CorruptionFoll
1c2d0 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f  owingBusyError</
1c2e0 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72  a> wiki page for
1c2f0 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66   a discussion of
1c300 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20   why.** this is 
1c310 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a  important..**.**
1c320 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c   ^(There can onl
1c330 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75  y be a single bu
1c340 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e  sy handler defin
1c350 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b  ed for each.** [
1c360 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1c370 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61  ion].  Setting a
1c380 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65   new busy handle
1c390 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20  r clears any.** 
1c3a0 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68  previously set h
1c3b0 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65  andler.)^  ^Note
1c3c0 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73   that calling [s
1c3d0 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65  qlite3_busy_time
1c3e0 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61  out()].** will a
1c3f0 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72  lso set or clear
1c400 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
1c410 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73  r..**.** The bus
1c420 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c  y callback shoul
1c430 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61  d not take any a
1c440 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64  ctions which mod
1c450 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  ify the.** datab
1c460 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
1c470 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
1c480 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41  busy handler.  A
1c490 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a  ny such actions.
1c4a0 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  ** result in und
1c4b0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
1c4c0 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68  .** .** A busy h
1c4d0 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20  andler must not 
1c4e0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
1c4f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
1c500 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74   or [prepared st
1c510 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e  atement] that in
1c520 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68  voked the busy h
1c530 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54  andler..*/.SQLIT
1c540 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
1c550 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73  3_busy_handler(s
1c560 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28  qlite3*, int(*)(
1c570 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64  void*,int), void
1c580 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1c590 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20  REF: Set A Busy 
1c5a0 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54  Timeout.**.** ^T
1c5b0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
1c5c0 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79   a [sqlite3_busy
1c5d0 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20  _handler | busy 
1c5e0 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c  handler] that sl
1c5f0 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70  eeps.** for a sp
1c600 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f  ecified amount o
1c610 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61  f time when a ta
1c620 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20  ble is locked.  
1c630 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  ^The handler.** 
1c640 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69  will sleep multi
1c650 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20  ple times until 
1c660 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69  at least "ms" mi
1c670 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c  lliseconds of sl
1c680 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61  eeping.** have a
1c690 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66  ccumulated.  ^Af
1c6a0 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73  ter at least "ms
1c6b0 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  " milliseconds o
1c6c0 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74  f sleeping,.** t
1c6d0 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72  he handler retur
1c6e0 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65  ns 0 which cause
1c6f0 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  s [sqlite3_step(
1c700 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20  )] to return.** 
1c710 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
1c720 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
1c730 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  LOCKED]..**.** ^
1c740 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75  Calling this rou
1c750 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67  tine with an arg
1c760 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20  ument less than 
1c770 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f  or equal to zero
1c780 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c  .** turns off al
1c790 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e  l busy handlers.
1c7a0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
1c7b0 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
1c7c0 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
1c7d0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
1c7e0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1c7f0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61  onnection] any a
1c800 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e  ny given moment.
1c810 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73    If another bus
1c820 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73  y handler.** was
1c830 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67   defined  (using
1c840 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68   [sqlite3_busy_h
1c850 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72  andler()]) prior
1c860 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74   to calling.** t
1c870 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61  his routine, tha
1c880 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  t other busy han
1c890 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e  dler is cleared.
1c8a0 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )^.*/.SQLITE_API
1c8b0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73   int sqlite3_bus
1c8c0 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
1c8d0 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
1c8e0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1c8f0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
1c900 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
1c910 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69  ueries.**.** Thi
1c920 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
1c930 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
1c940 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
1c950 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1c960 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
1c970 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
1c980 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
1c990 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
1c9a0 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
1c9b0 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
1c9c0 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
1c9d0 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
1c9e0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1c9f0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
1ca00 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
1ca10 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
1ca20 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
1ca30 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
1ca40 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
1ca50 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
1ca60 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
1ca70 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
1ca80 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
1ca90 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
1caa0 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
1cab0 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
1cac0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
1cad0 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
1cae0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
1caf0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
1cb00 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
1cb10 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
1cb20 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
1cb30 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
1cb40 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1cb50 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
1cb60 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
1cb70 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1cb80 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
1cb90 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
1cba0 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
1cbb0 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
1cbc0 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
1cbd0 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
1cbe0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
1cbf0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
1cc00 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
1cc10 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
1cc20 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
1cc30 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
1cc40 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
1cc50 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
1cc60 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
1cc70 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
1cc80 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
1cc90 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
1cca0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
1ccb0 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
1ccc0 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
1ccd0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1cce0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
1ccf0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
1cd00 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
1cd10 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
1cd20 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
1cd30 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
1cd40 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
1cd50 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
1cd60 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
1cd70 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
1cd80 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
1cd90 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
1cda0 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
1cdb0 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
1cdc0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
1cdd0 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
1cde0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
1cdf0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
1ce00 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
1ce10 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
1ce20 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
1ce30 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
1ce40 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
1ce50 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
1ce60 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1ce70 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
1ce80 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
1ce90 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
1cea0 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
1ceb0 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
1cec0 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
1ced0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1cee0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
1cef0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
1cf00 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
1cf10 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
1cf20 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
1cf30 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
1cf40 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
1cf50 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
1cf60 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
1cf70 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
1cf80 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
1cf90 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
1cfa0 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
1cfb0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1cfc0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1cfd0 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
1cfe0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1cff0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
1d000 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
1d010 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
1d020 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
1d030 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1d040 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
1d050 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1d060 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
1d070 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1d080 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
1d090 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1d0a0 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
1d0b0 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
1d0c0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
1d0d0 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
1d0e0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
1d0f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1d100 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
1d110 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
1d120 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
1d130 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
1d140 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
1d150 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
1d160 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
1d170 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
1d180 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
1d190 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
1d1a0 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
1d1b0 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
1d1c0 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
1d1d0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
1d1e0 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
1d1f0 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
1d200 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
1d210 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
1d220 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
1d230 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
1d240 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
1d250 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
1d260 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
1d270 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
1d280 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
1d290 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
1d2a0 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
1d2b0 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
1d2c0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
1d2d0 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
1d2e0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1d2f0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
1d300 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
1d310 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
1d320 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
1d330 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
1d340 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
1d350 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
1d360 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
1d370 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
1d380 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
1d390 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
1d3a0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
1d3b0 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
1d3c0 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
1d3d0 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
1d3e0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
1d3f0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
1d400 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
1d410 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
1d420 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
1d430 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
1d440 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
1d450 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
1d460 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
1d470 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
1d480 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
1d490 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
1d4a0 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
1d4b0 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
1d4c0 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
1d4d0 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
1d4e0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
1d4f0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
1d500 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
1d510 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
1d520 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1d530 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
1d540 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
1d550 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
1d560 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d570 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
1d580 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20            /* An 
1d590 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f  open database */
1d5a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
1d5b0 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20  Sql,     /* SQL 
1d5c0 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
1d5d0 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a  */.  char ***paz
1d5e0 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65  Result,    /* Re
1d5f0 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65  sults of the que
1d600 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52  ry */.  int *pnR
1d610 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a  ow,           /*
1d620 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1d630 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68  t rows written h
1d640 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ere */.  int *pn
1d650 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f  Column,        /
1d660 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
1d670 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74  lt columns writt
1d680 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61  en here */.  cha
1d690 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20  r **pzErrmsg    
1d6a0 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20     /* Error msg 
1d6b0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1d6c0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
1d6d0 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
1d6e0 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1d6f0 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1d700 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1d710 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1d720 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1d730 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1d740 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1d750 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1d760 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1d770 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1d780 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1d790 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
1d7a0 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1d7b0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
1d7c0 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
1d7d0 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
1d7e0 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
1d7f0 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1d800 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1d810 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
1d820 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1d830 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
1d840 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
1d850 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
1d860 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1d870 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
1d880 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
1d890 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
1d8a0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1d8b0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1d8c0 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1d8d0 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1d8e0 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1d8f0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1d900 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1d910 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1d920 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1d930 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1d940 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1d950 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1d960 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1d970 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1d980 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1d990 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1d9a0 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1d9b0 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1d9c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1d9d0 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1d9e0 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1d9f0 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1da00 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1da10 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1da20 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1da30 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1da40 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1da50 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1da60 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1da70 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1da80 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1da90 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1daa0 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1dab0 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1dac0 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1dad0 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1dae0 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1daf0 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1db00 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1db10 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1db20 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1db30 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1db40 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1db50 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1db60 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1db70 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1db80 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1db90 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1dba0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1dbb0 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1dbc0 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1dbd0 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1dbe0 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1dbf0 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1dc00 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1dc10 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1dc20 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1dc30 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1dc40 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1dc50 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1dc60 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1dc70 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1dc80 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1dc90 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1dca0 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1dcb0 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1dcc0 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1dcd0 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1dce0 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1dcf0 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1dd00 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1dd10 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1dd20 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1dd30 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1dd40 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1dd50 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1dd60 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1dd70 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1dd80 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
1dd90 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
1dda0 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
1ddb0 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
1ddc0 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
1ddd0 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
1dde0 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
1ddf0 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
1de00 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
1de10 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
1de20 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
1de30 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
1de40 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
1de50 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1de60 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1de70 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1de80 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1de90 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1dea0 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1deb0 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1dec0 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1ded0 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1dee0 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1def0 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1df00 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1df10 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1df20 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1df30 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1df40 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1df50 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1df60 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1df70 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1df80 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1df90 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1dfa0 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1dfb0 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1dfc0 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1dfd0 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1dfe0 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1dff0 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1e000 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1e010 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1e020 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1e030 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1e040 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1e050 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1e060 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1e070 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1e080 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1e090 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1e0a0 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1e0b0 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1e0c0 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1e0d0 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1e0e0 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1e0f0 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1e100 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1e110 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1e120 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1e130 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1e140 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1e150 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1e160 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1e170 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1e180 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1e190 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1e1a0 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1e1b0 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1e1c0 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1e1d0 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1e1e0 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1e1f0 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1e200 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1e210 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1e220 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1e230 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1e240 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1e250 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1e260 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1e270 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1e280 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1e290 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1e2a0 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1e2b0 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1e2c0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e2d0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1e2e0 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1e2f0 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1e300 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1e310 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1e320 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1e330 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1e340 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1e350 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1e360 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1e370 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1e380 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1e390 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1e3a0 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1e3b0 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1e3c0 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1e3d0 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1e3e0 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1e3f0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1e400 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1e410 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1e420 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1e430 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1e440 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1e450 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1e460 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1e470 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1e480 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1e490 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1e4a0 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1e4b0 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1e4c0 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1e4d0 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1e4e0 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1e4f0 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1e500 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1e510 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1e520 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1e530 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e540 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1e550 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1e560 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1e570 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1e580 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1e590 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1e5a0 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1e5b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1e5c0 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
1e5d0 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1e5e0 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
1e5f0 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
1e600 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
1e610 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
1e620 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
1e630 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
1e640 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
1e650 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
1e660 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
1e670 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
1e680 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61  /.SQLITE_API cha
1e690 72 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  r *sqlite3_mprin
1e6a0 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e  tf(const char*,.
1e6b0 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..);.SQLITE_API 
1e6c0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d  char *sqlite3_vm
1e6d0 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61  printf(const cha
1e6e0 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51  r*, va_list);.SQ
1e6f0 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1e700 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1e710 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1e720 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c  char*, ...);.SQL
1e730 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1e740 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
1e750 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20  int,char*,const 
1e760 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1e770 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1e780 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
1e790 69 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a  ion Subsystem.**
1e7a0 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63  .** The SQLite c
1e7b0 6f 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74  ore uses these t
1e7c0 68 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f  hree routines fo
1e7d0 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e  r all of its own
1e7e0 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d  .** internal mem
1e7f0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
1e800 65 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20  eeds. "Core" in 
1e810 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
1e820 74 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f  tence.** does no
1e830 74 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74  t include operat
1e840 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69  ing-system speci
1e850 66 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  fic VFS implemen
1e860 74 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20  tation.  The.** 
1e870 57 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73  Windows VFS uses
1e880 20 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29   native malloc()
1e890 20 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20   and free() for 
1e8a0 73 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e  some operations.
1e8b0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e8c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75  te3_malloc() rou
1e8d0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70  tine returns a p
1e8e0 6f 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63  ointer to a bloc
1e8f0 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61  k.** of memory a
1e900 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1e910 69 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65  in length, where
1e920 20 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65   N is the parame
1e930 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ter..** ^If sqli
1e940 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20  te3_malloc() is 
1e950 75 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e  unable to obtain
1e960 20 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65   sufficient free
1e970 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72  .** memory, it r
1e980 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
1e990 69 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20  inter.  ^If the 
1e9a0 70 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a  parameter N to.*
1e9b0 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  * sqlite3_malloc
1e9c0 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65  () is zero or ne
1e9d0 67 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69  gative then sqli
1e9e0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74  te3_malloc() ret
1e9f0 75 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70  urns.** a NULL p
1ea00 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ointer..**.** ^C
1ea10 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  alling sqlite3_f
1ea20 72 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69  ree() with a poi
1ea30 6e 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20  nter previously 
1ea40 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1ea50 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1ea60 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1ea70 6f 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68  oc() releases th
1ea80 61 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20  at memory so.** 
1ea90 74 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65  that it might be
1eaa0 20 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73   reused.  ^The s
1eab0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f  qlite3_free() ro
1eac0 75 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f  utine is.** a no
1ead0 2d 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64  -op if is called
1eae0 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
1eaf0 6e 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61  nter.  Passing a
1eb00 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
1eb10 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65   to sqlite3_free
1eb20 28 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20  () is harmless. 
1eb30 20 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65   After being fre
1eb40 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68  ed, memory.** sh
1eb50 6f 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20  ould neither be 
1eb60 72 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e  read nor written
1eb70 2e 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20  .  Even reading 
1eb80 70 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64  previously freed
1eb90 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74  .** memory might
1eba0 20 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67   result in a seg
1ebb0 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20  mentation fault 
1ebc0 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1ebd0 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79  error..** Memory
1ebe0 20 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73   corruption, a s
1ebf0 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c  egmentation faul
1ec00 74 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65  t, or other seve
1ec10 72 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68  re error.** migh
1ec20 74 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69  t result if sqli
1ec30 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61  te3_free() is ca
1ec40 6c 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d  lled with a non-
1ec50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61  NULL pointer tha
1ec60 74 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74  t.** was not obt
1ec70 61 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74  ained from sqlit
1ec80 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73  e3_malloc() or s
1ec90 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1eca0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
1ecb0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1ecc0 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70  interface attemp
1ecd0 74 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a  ts to resize a.*
1ece0 2a 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61  * prior memory a
1ecf0 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1ed00 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73  at least N bytes
1ed10 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
1ed20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1ed30 65 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72  eter.  The memor
1ed40 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
1ed50 62 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68  be resized is th
1ed60 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d  e first.** param
1ed70 65 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65  eter.)^ ^ If the
1ed80 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
1ed90 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
1eda0 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55  loc().** is a NU
1edb0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1edc0 69 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20  its behavior is 
1edd0 69 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c  identical to cal
1ede0 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ling.** sqlite3_
1edf0 6d 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20  malloc(N) where 
1ee00 4e 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20  N is the second 
1ee10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1ee20 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1ee30 2a 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  ** ^If the secon
1ee40 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
1ee50 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ee60 20 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e   is zero or.** n
1ee70 65 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65  egative then the
1ee80 20 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61   behavior is exa
1ee90 63 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73  ctly the same as
1eea0 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1eeb0 74 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72  te3_free(P) wher
1eec0 65 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74  e P is the first
1eed0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1eee0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1eef0 0a 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61  .** ^sqlite3_rea
1ef00 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61  lloc() returns a
1ef10 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
1ef20 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a  mory allocation.
1ef30 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e  ** of at least N
1ef40 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f   bytes in size o
1ef50 72 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63  r NULL if suffic
1ef60 69 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75  ient memory is u
1ef70 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e  navailable..** ^
1ef80 49 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65  If M is the size
1ef90 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1efa0 6c 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d  location, then m
1efb0 69 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a  in(N,M) bytes.**
1efc0 20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c   of the prior al
1efd0 6c 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70  location are cop
1efe0 69 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67  ied into the beg
1eff0 69 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72  inning of buffer
1f000 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20   returned.** by 
1f010 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f020 29 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20  ) and the prior 
1f030 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72  allocation is fr
1f040 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  eed..** ^If sqli
1f050 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1f060 74 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  turns NULL, then
1f070 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1f080 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20  ation.** is not 
1f090 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  freed..**.** ^Th
1f0a0 65 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65  e memory returne
1f0b0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c  d by sqlite3_mal
1f0c0 6c 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65  loc() and sqlite
1f0d0 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69  3_realloc().** i
1f0e0 73 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64  s always aligned
1f0f0 20 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20   to at least an 
1f100 38 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c  8 byte boundary,
1f110 20 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79   or to a.** 4 by
1f120 74 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74  te boundary if t
1f130 68 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54  he [SQLITE_4_BYT
1f140 45 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43  E_ALIGNED_MALLOC
1f150 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a  ] compile-time.*
1f160 2a 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  * option is used
1f170 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74  ..**.** In SQLit
1f180 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20  e version 3.5.0 
1f190 61 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61  and 3.5.1, it wa
1f1a0 73 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65  s possible to de
1f1b0 66 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49  fine.** the SQLI
1f1c0 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41  TE_OMIT_MEMORY_A
1f1d0 4c 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20  LLOCATION which 
1f1e0 77 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20  would cause the 
1f1f0 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c  built-in.** impl
1f200 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
1f210 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ese routines to 
1f220 62 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61  be omitted.  Tha
1f230 74 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  t capability.** 
1f240 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f  is no longer pro
1f250 76 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69  vided.  Only bui
1f260 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1f270 6f 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75  ocators can be u
1f280 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72  sed..**.** Prior
1f290 20 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69   to SQLite versi
1f2a0 6f 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57  on 3.7.10, the W
1f2b0 69 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66  indows OS interf
1f2c0 61 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64  ace layer called
1f2d0 0a 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d  .** the system m
1f2e0 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
1f2f0 28 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e  () directly when
1f300 20 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66   converting.** f
1f310 69 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e  ilenames between
1f320 20 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64   the UTF-8 encod
1f330 69 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69  ing used by SQLi
1f340 74 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76  te.** and whatev
1f350 65 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f  er filename enco
1f360 64 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20  ding is used by 
1f370 74 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57  the particular W
1f380 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c  indows.** instal
1f390 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20  lation.  Memory 
1f3a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
1f3b0 73 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c  s were detected,
1f3c0 20 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72   but.** they wer
1f3d0 65 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20  e reported back 
1f3e0 61 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f  as [SQLITE_CANTO
1f3f0 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  PEN] or.** [SQLI
1f400 54 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72  TE_IOERR] rather
1f410 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f   than [SQLITE_NO
1f420 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  MEM]..**.** The 
1f430 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74  pointer argument
1f440 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  s to [sqlite3_fr
1f450 65 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ee()] and [sqlit
1f460 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1f470 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
1f480 4e 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69  NULL or else poi
1f490 6e 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66  nters obtained f
1f4a0 72 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69  rom a prior.** i
1f4b0 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71  nvocation of [sq
1f4c0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1f4d0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  or [sqlite3_real
1f4e0 6c 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65  loc()] that have
1f4f0 0a 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e  .** not yet been
1f500 20 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a   released..**.**
1f510 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
1f520 20 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f   must not read o
1f530 72 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74  r write any part
1f540 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f   of.** a block o
1f550 66 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69  f memory after i
1f560 74 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61  t has been relea
1f570 73 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  sed using.** [sq
1f580 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72  lite3_free()] or
1f590 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1f5a0 63 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  c()]..*/.SQLITE_
1f5b0 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  API void *sqlite
1f5c0 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53  3_malloc(int);.S
1f5d0 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a  QLITE_API void *
1f5e0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1f5f0 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c  void*, int);.SQL
1f600 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c  ITE_API void sql
1f610 69 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29  ite3_free(void*)
1f620 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1f630 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
1f640 74 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a  tor Statistics.*
1f650 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76  *.** SQLite prov
1f660 69 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69  ides these two i
1f670 6e 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65  nterfaces for re
1f680 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73  porting on the s
1f690 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20  tatus.** of the 
1f6a0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1f6b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  )], [sqlite3_fre
1f6c0 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
1f6d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a  e3_realloc()].**
1f6e0 20 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68   routines, which
1f6f0 20 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d   form the built-
1f700 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1f710 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a  tion subsystem..
1f720 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
1f730 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1f740 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1f750 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1f760 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d   bytes.** of mem
1f770 6f 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75  ory currently ou
1f780 74 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f  tstanding (mallo
1f790 63 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65  ced but not free
1f7a0 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c  d)..** ^The [sql
1f7b0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1f7c0 77 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65  water()] routine
1f7d0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78   returns the max
1f7e0 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66  imum.** value of
1f7f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1f800 5f 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74  _used()] since t
1f810 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
1f820 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72  rk.** was last r
1f830 65 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75  eset.  ^The valu
1f840 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
1f850 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1f860 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73  sed()] and.** [s
1f870 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1f880 67 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75  ghwater()] inclu
1f890 64 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a  de any overhead.
1f8a0 2a 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69  ** added by SQLi
1f8b0 74 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d  te in its implem
1f8c0 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  entation of [sql
1f8d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a  ite3_malloc()],.
1f8e0 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68  ** but not overh
1f8f0 65 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65  ead added by the
1f900 20 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20   any underlying 
1f910 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a  system library.*
1f920 2a 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20  * routines that 
1f930 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1f940 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a  )] may call..**.
1f950 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68  ** ^The memory h
1f960 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69  igh-water mark i
1f970 73 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63  s reset to the c
1f980 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a  urrent value of.
1f990 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  ** [sqlite3_memo
1f9a0 72 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e  ry_used()] if an
1f9b0 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61  d only if the pa
1f9c0 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
1f9d0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1f9e0 67 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72  ghwater()] is tr
1f9f0 75 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20  ue.  ^The value 
1fa00 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b  returned.** by [
1fa10 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1fa20 69 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20  ighwater(1)] is 
1fa30 74 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d  the high-water m
1fa40 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  ark.** prior to 
1fa50 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51  the reset..*/.SQ
1fa60 4c 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33  LITE_API sqlite3
1fa70 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d  _int64 sqlite3_m
1fa80 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29  emory_used(void)
1fa90 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c  ;.SQLITE_API sql
1faa0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
1fab0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1fac0 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61  ter(int resetFla
1fad0 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  g);../*.** CAPI3
1fae0 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64  REF: Pseudo-Rand
1faf0 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61  om Number Genera
1fb00 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  tor.**.** SQLite
1fb10 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68   contains a high
1fb20 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d  -quality pseudo-
1fb30 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65  random number ge
1fb40 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75  nerator (PRNG) u
1fb50 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74  sed to.** select
1fb60 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c   random [ROWID |
1fb70 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e   ROWIDs] when in
1fb80 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f  serting new reco
1fb90 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65  rds into a table
1fba0 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79   that.** already
1fbb0 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73   uses the larges
1fbc0 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49  t possible [ROWI
1fbd0 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73  D].  The PRNG is
1fbe0 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a   also used for.*
1fbf0 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72  * the build-in r
1fc00 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64  andom() and rand
1fc10 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e  omblob() SQL fun
1fc20 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e  ctions.  This in
1fc30 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a  terface allows.*
1fc40 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * applications t
1fc50 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d  o access the sam
1fc60 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72  e PRNG for other
1fc70 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a   purposes..**.**
1fc80 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73   ^A call to this
1fc90 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20   routine stores 
1fca0 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f  N bytes of rando
1fcb0 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65  mness into buffe
1fcc0 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  r P..**.** ^The 
1fcd0 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20  first time this 
1fce0 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b  routine is invok
1fcf0 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72  ed (either inter
1fd00 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74  nally or by.** t
1fd10 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20  he application) 
1fd20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64  the PRNG is seed
1fd30 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e  ed using randomn
1fd40 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ess obtained.** 
1fd50 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d  from the xRandom
1fd60 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74  ness method of t
1fd70 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69  he default [sqli
1fd80 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e  te3_vfs] object.
1fd90 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73  .** ^On all subs
1fda0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
1fdb0 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72  ns, the pseudo-r
1fdc0 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e  andomness is gen
1fdd0 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e  erated.** intern
1fde0 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74  ally and without
1fdf0 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65   recourse to the
1fe00 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78   [sqlite3_vfs] x
1fe10 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65  Randomness.** me
1fe20 74 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  thod..*/.SQLITE_
1fe30 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
1fe40 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20  _randomness(int 
1fe50 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a  N, void *P);../*
1fe60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
1fe70 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f  mpile-Time Autho
1fe80 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63  rization Callbac
1fe90 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ks.**.** ^This r
1fea0 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73  outine registers
1feb0 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   an authorizer c
1fec0 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70  allback with a p
1fed0 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61  articular.** [da
1fee0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1fef0 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20  n], supplied in 
1ff00 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
1ff10 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68  nt..** ^The auth
1ff20 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1ff30 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51  is invoked as SQ
1ff40 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
1ff50 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a   being compiled.
1ff60 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70  ** by [sqlite3_p
1ff70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73  repare()] or its
1ff80 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74   variants [sqlit
1ff90 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1ffa0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  ,.** [sqlite3_pr
1ffb0 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b  epare16()] and [
1ffc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
1ffd0 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61  6_v2()].  ^At va
1ffe0 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20  rious.** points 
1fff0 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69  during the compi
20000 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20  lation process, 
20010 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e  as logic is bein
20020 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20  g created.** to 
20030 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20  perform various 
20040 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74  actions, the aut
20050 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20060 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a   is invoked to.*
20070 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61  * see if those a
20080 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77  ctions are allow
20090 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72  ed.  ^The author
200a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68  izer callback sh
200b0 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  ould.** return [
200c0 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c  SQLITE_OK] to al
200d0 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20  low the action, 
200e0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
200f0 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a  to disallow the.
20100 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69  ** specific acti
20110 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65  on but allow the
20120 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74   SQL statement t
20130 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65  o continue to be
20140 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72  .** compiled, or
20150 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74   [SQLITE_DENY] t
20160 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69  o cause the enti
20170 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  re SQL statement
20180 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74   to be.** reject
20190 65 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ed with an error
201a0 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f  .  ^If the autho
201b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72  rizer callback r
201c0 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61  eturns.** any va
201d0 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  lue other than [
201e0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20  SQLITE_IGNORE], 
201f0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20  [SQLITE_OK], or 
20200 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a  [SQLITE_DENY].**
20210 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74   then the [sqlit
20220 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
20230 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
20240 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
20250 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72  ed.** the author
20260 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
20270 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
20280 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  sage..**.** When
20290 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
202a0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b  turns [SQLITE_OK
202b0 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68  ], that means th
202c0 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72  e operation.** r
202d0 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20  equested is ok. 
202e0 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62   ^When the callb
202f0 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
20300 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a  ITE_DENY], the.*
20310 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
20320 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
20330 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
20340 20 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a   triggered the.*
20350 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  * authorizer wil
20360 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
20370 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70  rror message exp
20380 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20  laining that.** 
20390 61 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64  access is denied
203a0 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  . .**.** ^The fi
203b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
203c0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
203d0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f  callback is a co
203e0 70 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a  py of the third.
203f0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
20400 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  the sqlite3_set_
20410 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74  authorizer() int
20420 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63  erface. ^The sec
20430 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ond parameter.**
20440 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
20450 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b   is an integer [
20460 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63  SQLITE_COPY | ac
20470 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20  tion code] that 
20480 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65  specifies.** the
20490 20 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69   particular acti
204a0 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69  on to be authori
204b0 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20  zed. ^The third 
204c0 74 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61  through sixth pa
204d0 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74  rameters.** to t
204e0 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20  he callback are 
204f0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
20500 73 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e  strings that con
20510 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a  tain additional.
20520 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74  ** details about
20530 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62   the action to b
20540 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a  e authorized..**
20550 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69  .** ^If the acti
20560 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49  on code is [SQLI
20570 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20  TE_READ].** and 
20580 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20590 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e  urns [SQLITE_IGN
205a0 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a  ORE] then the.**
205b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
205c0 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20  ment] statement 
205d0 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74  is constructed t
205e0 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20  o substitute.** 
205f0 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20  a NULL value in 
20600 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62  place of the tab
20610 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77  le column that w
20620 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65  ould have.** bee
20630 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54  n read if [SQLIT
20640 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72  E_OK] had been r
20650 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53  eturned.  The [S
20660 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a  QLITE_IGNORE].**
20670 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75   return can be u
20680 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75  sed to deny an u
20690 6e 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63  ntrusted user ac
206a0 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75  cess to individu
206b0 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66  al.** columns of
206c0 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66   a table..** ^If
206d0 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
206e0 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45   is [SQLITE_DELE
206f0 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  TE] and the call
20700 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
20710 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20  [SQLITE_IGNORE] 
20720 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45  then the [DELETE
20730 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63  ] operation proc
20740 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20  eeds but the.** 
20750 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69  [truncate optimi
20760 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62  zation] is disab
20770 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73  led and all rows
20780 20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64   are deleted ind
20790 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  ividually..**.**
207a0 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69   An authorizer i
207b0 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c  s used when [sql
207c0 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70  ite3_prepare | p
207d0 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c  reparing].** SQL
207e0 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d   statements from
207f0 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f   an untrusted so
20800 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20  urce, to ensure 
20810 74 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61  that the SQL sta
20820 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f  tements.** do no
20830 74 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20  t try to access 
20840 64 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f  data they are no
20850 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65  t allowed to see
20860 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64  , or that they d
20870 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20  o not.** try to 
20880 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75  execute maliciou
20890 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61  s statements tha
208a0 74 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74  t damage the dat
208b0 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65  abase.  For.** e
208c0 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69  xample, an appli
208d0 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77  cation may allow
208e0 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72   a user to enter
208f0 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51   arbitrary.** SQ
20900 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76  L queries for ev
20910 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61  aluation by a da
20920 74 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65  tabase.  But the
20930 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65   application doe
20940 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68  s.** not want th
20950 65 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c  e user to be abl
20960 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72  e to make arbitr
20970 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ary changes to t
20980 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  he.** database. 
20990 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63   An authorizer c
209a0 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74  ould then be put
209b0 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20   in place while 
209c0 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65  the.** user-ente
209d0 72 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67  red SQL is being
209e0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
209f0 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68  e | prepared] th
20a00 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20  at.** disallows 
20a10 65 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70  everything excep
20a20 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  t [SELECT] state
20a30 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70  ments..**.** App
20a40 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e  lications that n
20a50 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53  eed to process S
20a60 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65  QL from untruste
20a70 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67  d sources.** mig
20a80 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72  ht also consider
20a90 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72   lowering resour
20aa0 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20  ce limits using 
20ab0 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
20ac0 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e  ].** and limitin
20ad0 67 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20  g database size 
20ae0 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70  using the [max_p
20af0 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47  age_count] [PRAG
20b00 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69  MA].** in additi
20b10 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61  on to using an a
20b20 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a  uthorizer..**.**
20b30 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65   ^(Only a single
20b40 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20   authorizer can 
20b50 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61  be in place on a
20b60 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
20b70 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d  tion.** at a tim
20b80 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f  e.  Each call to
20b90 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
20ba0 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65  horizer override
20bb0 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75  s the.** previou
20bc0 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61  s call.)^  ^Disa
20bd0 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ble the authoriz
20be0 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67  er by installing
20bf0 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b   a NULL callback
20c00 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69  ..** The authori
20c10 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20  zer is disabled 
20c20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a  by default..**.*
20c30 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * The authorizer
20c40 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
20c50 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
20c60 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
20c70 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
20c80 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
20c90 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68  invoked the auth
20ca0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e  orizer callback.
20cb0 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73  .** Note that [s
20cc0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
20cd0 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
20ce0 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d  3_step()] both m
20cf0 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64  odify their.** d
20d00 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
20d10 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e  ons for the mean
20d20 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20  ing of "modify" 
20d30 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70  in this paragrap
20d40 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b  h..**.** ^When [
20d50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20d60 76 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f  v2()] is used to
20d70 20 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65   prepare a state
20d80 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61  ment, the.** sta
20d90 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20  tement might be 
20da0 72 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69  re-prepared duri
20db0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
20dc0 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a  ()] due to a .**
20dd0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20   schema change. 
20de0 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c   Hence, the appl
20df0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65  ication should e
20e00 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a  nsure that the.*
20e10 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72  * correct author
20e20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
20e30 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64  mains in place d
20e40 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74  uring the [sqlit
20e50 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a  e3_step()]..**.*
20e60 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65  * ^Note that the
20e70 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
20e80 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
20e90 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b  only during.** [
20ea0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
20eb0 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
20ec0 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69  ts.  Authorizati
20ed0 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72  on is not.** per
20ee0 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74  formed during st
20ef0 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69  atement evaluati
20f00 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73  on in [sqlite3_s
20f10 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a  tep()], unless.*
20f20 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74  * as stated in t
20f30 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
20f40 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73  graph, sqlite3_s
20f50 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a  tep() invokes.**
20f60 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
20f70 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61  _v2() to reprepa
20f80 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61  re a statement a
20f90 66 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68  fter a schema ch
20fa0 61 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  ange..*/.SQLITE_
20fb0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
20fc0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a  set_authorizer(.
20fd0 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e    sqlite3*,.  in
20fe0 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a  t (*xAuth)(void*
20ff0 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a  ,int,const char*
21000 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
21010 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  st char*,const c
21020 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70  har*),.  void *p
21030 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a  UserData.);../*.
21040 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
21050 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43  horizer Return C
21060 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
21070 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21080 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
21090 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  zer callback fun
210a0 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72  ction] must.** r
210b0 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51  eturn either [SQ
210c0 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20  LITE_OK] or one 
210d0 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e  of these two con
210e0 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a  stants in order.
210f0 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c  ** to signal SQL
21100 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ite whether or n
21110 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73  ot the action is
21120 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65   permitted.  See
21130 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
21140 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
21150 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63  | authorizer doc
21160 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20  umentation] for 
21170 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
21180 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
21190 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54   Note that SQLIT
211a0 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f  E_IGNORE is also
211b0 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49   used as a [SQLI
211c0 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65  TE_ROLLBACK | re
211d0 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72  turn code].** fr
211e0 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
211f0 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74  vtab_on_conflict
21200 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
21210 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21220 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41  _DENY   1   /* A
21230 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61  bort the SQL sta
21240 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65  tement with an e
21250 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
21260 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20  SQLITE_IGNORE 2 
21270 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77    /* Don't allow
21280 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e   access, but don
21290 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65  't generate an e
212a0 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  rror */../*.** C
212b0 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69  API3REF: Authori
212c0 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73  zer Action Codes
212d0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  .**.** The [sqli
212e0 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
212f0 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  er()] interface 
21300 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c  registers a call
21310 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a  back function.**
21320 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64   that is invoked
21330 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65   to authorize ce
21340 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d  rtain SQL statem
21350 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68  ent actions.  Th
21360 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61  e.** second para
21370 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c  meter to the cal
21380 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65  lback is an inte
21390 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70  ger code that sp
213a0 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20  ecifies.** what 
213b0 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20  action is being 
213c0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
213d0 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67  se are the integ
213e0 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20  er action codes 
213f0 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68  that.** the auth
21400 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
21410 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a  may be passed..*
21420 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f  *.** These actio
21430 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69  n code values si
21440 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20  gnify what kind 
21450 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  of operation is 
21460 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69  to be.** authori
21470 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e  zed.  The 3rd an
21480 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73  d 4th parameters
21490 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
214a0 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63  ation.** callbac
214b0 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20  k function will 
214c0 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72  be parameters or
214d0 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20   NULL depending 
214e0 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73  on which of thes
214f0 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73  e.** codes is us
21500 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
21510 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54   parameter.  ^(T
21520 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
21530 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f   to the.** autho
21540 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
21550 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
21560 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69  e database ("mai
21570 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65  n", "temp",.** e
21580 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62  tc.) if applicab
21590 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20  le.)^  ^The 6th 
215a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
215b0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
215c0 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e  back.** is the n
215d0 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72  ame of the inner
215e0 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72  -most trigger or
215f0 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65   view that is re
21600 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a  sponsible for.**
21610 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65   the access atte
21620 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74  mpt or NULL if t
21630 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d  his access attem
21640 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66  pt is directly f
21650 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c  rom.** top-level
21660 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a   SQL code..*/./*
21670 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21680 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21690 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a  ********** 3rd *
216a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20  *********** 4th 
216b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65  ***********/.#de
216c0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
216d0 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  TE_INDEX        
216e0 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e    1   /* Index N
216f0 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
21700 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21710 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
21720 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  E_TABLE         
21730 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   2   /* Table Na
21740 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21750 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21760 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
21770 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
21780 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  3   /* Index Nam
21790 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
217a0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
217b0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
217c0 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34  TEMP_TABLE     4
217d0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
217e0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
217f0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21800 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
21810 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20  EMP_TRIGGER   5 
21820 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
21830 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
21840 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21850 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
21860 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20  MP_VIEW      6  
21870 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
21880 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21890 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
218a0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49  QLITE_CREATE_TRI
218b0 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20  GGER        7   
218c0 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
218d0 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
218e0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
218f0 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57  LITE_CREATE_VIEW
21900 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f             8   /
21910 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
21920 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21930 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21940 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20  ITE_DELETE      
21950 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a            9   /*
21960 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21970 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21980 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21990 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20  TE_DROP_INDEX   
219a0 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20          10   /* 
219b0 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
219c0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
219d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
219e0 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20  E_DROP_TABLE    
219f0 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54         11   /* T
21a00 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
21a10 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21a20 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21a30 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58  _DROP_TEMP_INDEX
21a40 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e        12   /* In
21a50 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
21a60 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21a70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21a80 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20  DROP_TEMP_TABLE 
21a90 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62       13   /* Tab
21aa0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
21ab0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21ac0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21ad0 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52  ROP_TEMP_TRIGGER
21ae0 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67      14   /* Trig
21af0 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
21b00 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21b10 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
21b20 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20  OP_TEMP_VIEW    
21b30 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20     15   /* View 
21b40 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
21b50 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21b60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
21b70 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20  P_TRIGGER       
21b80 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65    16   /* Trigge
21b90 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
21ba0 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
21bb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21bc0 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20  _VIEW           
21bd0 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61   17   /* View Na
21be0 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
21bf0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
21c00 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52  ine SQLITE_INSER
21c10 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  T               
21c20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  18   /* Table Na
21c30 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21c40 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21c50 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41  ne SQLITE_PRAGMA
21c60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
21c70 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61  9   /* Pragma Na
21c80 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f  me     1st arg o
21c90 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e  r NULL */.#defin
21ca0 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20  e SQLITE_READ   
21cb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30                20
21cc0 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21cd0 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d        Column Nam
21ce0 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
21cf0 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20   SQLITE_SELECT  
21d00 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20               21 
21d10 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20    /* NULL       
21d20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
21d30 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21d40 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49  SQLITE_TRANSACTI
21d50 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20  ON          22  
21d60 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20   /* Operation   
21d70 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21d80 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21d90 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20  QLITE_UPDATE    
21da0 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20             23   
21db0 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
21dc0 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20     Column Name  
21dd0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21de0 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20  LITE_ATTACH     
21df0 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f            24   /
21e00 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20  * Filename      
21e10 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21e20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21e30 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20  ITE_DETACH      
21e40 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a           25   /*
21e50 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
21e60 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21e70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21e80 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20  TE_ALTER_TABLE  
21e90 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20          26   /* 
21ea0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
21eb0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21ec0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21ed0 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20  E_REINDEX       
21ee0 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49         27   /* I
21ef0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e  ndex Name      N
21f00 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21f10 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21f20 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20  _ANALYZE        
21f30 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61        28   /* Ta
21f40 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
21f50 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
21f60 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21f70 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20  CREATE_VTABLE   
21f80 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62       29   /* Tab
21f90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
21fa0 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
21fb0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
21fc0 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20  ROP_VTABLE      
21fd0 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c      30   /* Tabl
21fe0 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
21ff0 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
22000 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55  define SQLITE_FU
22010 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  NCTION          
22020 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20     31   /* NULL 
22030 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74             Funct
22040 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64  ion Name   */.#d
22050 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56  efine SQLITE_SAV
22060 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20  EPOINT          
22070 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74    32   /* Operat
22080 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f  ion       Savepo
22090 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65  int Name  */.#de
220a0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59  fine SQLITE_COPY
220b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
220c0 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67    0   /* No long
220d0 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a  er used */../*.*
220e0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
220f0 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
22100 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
22110 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
22120 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
22130 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
22140 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
22150 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
22160 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
22170 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
22180 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
22190 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
221a0 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
221b0 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
221c0 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
221d0 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
221e0 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
221f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
22200 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
22210 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
22220 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
22230 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
22240 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
22250 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
22260 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
22270 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
22280 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
22290 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
222a0 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
222b0 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
222c0 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
222d0 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
222e0 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
222f0 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
22300 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
22310 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
22320 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
22330 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
22340 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
22350 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
22360 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  )^.**.** ^The ca
22370 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
22380 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
22390 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20  lite3_profile() 
223a0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73  is invoked.** as
223b0 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d   each SQL statem
223c0 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e  ent finishes.  ^
223d0 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c  The profile call
223e0 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a  back contains.**
223f0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
22400 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64  atement text and
22410 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20   an estimate of 
22420 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a  wall-clock time.
22430 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74  ** of how long t
22440 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  hat statement to
22450 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65  ok to run.  ^The
22460 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63   profile callbac
22470 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20  k.** time is in 
22480 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63  units of nanosec
22490 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68  onds, however th
224a0 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d  e current implem
224b0 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f  entation.** is o
224c0 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d  nly capable of m
224d0 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c  illisecond resol
224e0 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78  ution so the six
224f0 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61   least significa
22500 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20  nt.** digits in 
22510 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61  the time are mea
22520 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72  ningless.  Futur
22530 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
22540 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72  Lite.** might pr
22550 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65  ovide greater re
22560 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20  solution on the 
22570 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63  profiler callbac
22580 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74  k.  The.** sqlit
22590 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e  e3_profile() fun
225a0 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65  ction is conside
225b0 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c  red experimental
225c0 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65   and is.** subje
225d0 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20  ct to change in 
225e0 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  future versions 
225f0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51  of SQLite..*/.SQ
22600 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
22610 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
22620 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
22630 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
22640 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
22650 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
22660 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20  TE_EXPERIMENTAL 
22670 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72  void *sqlite3_pr
22680 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a  ofile(sqlite3*,.
22690 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c     void(*xProfil
226a0 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63  e)(void*,const c
226b0 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e  har*,sqlite3_uin
226c0 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f  t64), void*);../
226d0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51  *.** CAPI3REF: Q
226e0 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61  uery Progress Ca
226f0 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54  llbacks.**.** ^T
22700 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72  he sqlite3_progr
22710 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c  ess_handler(D,N,
22720 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63  X,P) interface c
22730 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61  auses the callba
22740 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58  ck.** function X
22750 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70   to be invoked p
22760 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69  eriodically duri
22770 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20  ng long running 
22780 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
22790 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73  ite3_exec()], [s
227a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61  qlite3_step()] a
227b0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  nd [sqlite3_get_
227c0 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20  table()] for.** 
227d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
227e0 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70  ion D.  An examp
227f0 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a  le use for this.
22800 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
22810 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70  to keep a GUI up
22820 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c  dated during a l
22830 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a  arge query..**.*
22840 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72  * ^The parameter
22850 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72   P is passed thr
22860 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79  ough as the only
22870 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
22880 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66  e .** callback f
22890 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65  unction X.  ^The
228a0 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20   parameter N is 
228b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  the number of .*
228c0 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
228d0 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
228e0 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
228f0 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
22900 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
22910 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
22920 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e  lback X..**.** ^
22930 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72  Only a single pr
22940 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d  ogress handler m
22950 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74  ay be defined at
22960 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a   one time per.**
22970 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
22980 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20  ction]; setting 
22990 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68  a new progress h
229a0 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74  andler cancels t
229b0 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20  he.** old one.  
229c0 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74  ^Setting paramet
229d0 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73  er X to NULL dis
229e0 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65  ables the progre
229f0 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e  ss handler..** ^
22a00 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
22a10 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73  dler is also dis
22a20 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67  abled by setting
22a30 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65   N to a value le
22a40 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a  ss.** than 1..**
22a50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67  .** ^If the prog
22a60 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65  ress callback re
22a70 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
22a80 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  the operation is
22a90 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e  .** interrupted.
22aa0 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63    This feature c
22ab0 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d  an be used to im
22ac0 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61  plement a.** "Ca
22ad0 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20  ncel" button on 
22ae0 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64  a GUI progress d
22af0 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a  ialog box..**.**
22b00 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   The progress ha
22b10 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  ndler callback m
22b20 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68  ust not do anyth
22b30 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f  ing that will mo
22b40 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61  dify.** the data
22b50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
22b60 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65  that invoked the
22b70 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
22b80 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  r..** Note that 
22b90 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
22ba0 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
22bb0 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
22bc0 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
22bd0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
22be0 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
22bf0 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
22c00 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
22c10 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54  aph..**.*/.SQLIT
22c20 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
22c30 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
22c40 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
22c50 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
22c60 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
22c70 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
22c80 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
22c90 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
22ca0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
22cb0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
22cc0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
22cd0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
22ce0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
22cf0 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
22d00 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
22d10 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
22d20 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
22d30 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
22d40 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
22d50 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
22d60 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
22d70 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
22d80 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
22d90 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
22da0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
22db0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
22dc0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
22dd0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
22de0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
22df0 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
22e00 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
22e10 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
22e20 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
22e30 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
22e40 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
22e50 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
22e60 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
22e70 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
22e80 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
22e90 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
22ea0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
22eb0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
22ec0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
22ed0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
22ee0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
22ef0 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
22f00 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
22f10 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
22f20 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
22f30 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
22f40 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
22f50 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
22f60 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
22f70 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
22f80 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
22f90 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
22fa0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
22fb0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
22fc0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
22fd0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
22fe0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
22ff0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
23000 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
23010 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
23020 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
23030 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
23040 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
23050 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
23060 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
23070 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
23080 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
23090 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
230a0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
230b0 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
230c0 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
230d0 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
230e0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
230f0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
23100 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23110 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
23120 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
23130 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
23140 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
23150 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
23160 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
23170 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
23180 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
23190 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
231a0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
231b0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
231c0 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
231d0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
231e0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
231f0 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
23200 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
23210 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23220 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
23230 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
23240 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
23250 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
23260 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
23270 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
23280 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
23290 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
232a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
232b0 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
232c0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
232d0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
232e0 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
232f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
23300 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
23310 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
23320 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
23330 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
23340 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
23350 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
23360 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
23370 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
23380 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
23390 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
233a0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
233b0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
233c0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
233d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
233e0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
233f0 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
23400 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
23410 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
23420 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
23430 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
23440 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
23450 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
23460 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
23470 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
23480 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
23490 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
234a0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
234b0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
234c0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
234d0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
234e0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
234f0 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
23500 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
23510 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
23520 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
23530 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
23540 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
23550 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
23560 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
23570 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
23580 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
23590 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
235a0 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
235b0 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
235c0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
235d0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
235e0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
235f0 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
23600 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
23610 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
23620 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
23630 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
23640 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
23650 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
23660 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
23670 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
23680 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
23690 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
236a0 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
236b0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
236c0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
236d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
236e0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
236f0 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
23700 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23710 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
23720 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
23730 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
23740 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
23750 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
23760 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
23770 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
23780 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
23790 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
237a0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
237b0 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
237c0 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
237d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
237e0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
237f0 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
23800 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
23810 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
23820 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
23830 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
23840 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
23850 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
23860 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
23870 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
23880 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
23890 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
238a0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
238b0 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
238c0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
238d0 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
238e0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
238f0 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
23900 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
23910 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
23920 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
23930 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
23940 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
23950 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
23960 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
23970 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
23980 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
23990 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
239a0 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
239b0 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
239c0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
239d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
239e0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
239f0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
23a00 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
23a10 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
23a20 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
23a30 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
23a40 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
23a50 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
23a60 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
23a70 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
23a80 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
23a90 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
23aa0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
23ab0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
23ac0 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
23ad0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
23ae0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
23af0 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
23b00 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
23b10 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
23b20 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
23b30 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
23b40 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
23b50 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
23b60 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
23b70 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
23b80 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
23b90 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
23ba0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
23bb0 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
23bc0 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
23bd0 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
23be0 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
23bf0 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
23c00 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
23c10 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
23c20 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
23c30 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
23c40 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
23c50 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
23c60 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
23c70 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
23c80 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
23c90 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
23ca0 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
23cb0 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
23cc0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
23cd0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
23ce0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
23cf0 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
23d00 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
23d10 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
23d20 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
23d30 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
23d40 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
23d50 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
23d60 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
23d70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
23d80 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
23d90 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
23da0 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
23db0 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
23dc0 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
23dd0 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
23de0 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
23df0 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
23e00 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
23e10 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
23e20 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
23e30 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
23e40 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
23e50 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
23e60 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
23e70 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
23e80 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
23e90 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
23ea0 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
23eb0 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
23ec0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
23ed0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
23ee0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
23ef0 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
23f00 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
23f10 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
23f20 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
23f30 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
23f40 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
23f50 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
23f60 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
23f70 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
23f80 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
23f90 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
23fa0 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
23fb0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
23fc0 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
23fd0 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
23fe0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
23ff0 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
24000 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
24010 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
24020 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
24030 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
24040 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
24050 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
24060 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
24070 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
24080 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
24090 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
240a0 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
240b0 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
240c0 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
240d0 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
240e0 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
240f0 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
24100 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
24110 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
24120 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
24130 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
24140 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
24150 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
24160 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
24170 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
24180 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
24190 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
241a0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
241b0 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
241c0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
241d0 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
241e0 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
241f0 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
24200 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
24210 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
24220 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
24230 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
24240 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
24250 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
24260 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
24270 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
24280 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
24290 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
242a0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
242b0 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
242c0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
242d0 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
242e0 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
242f0 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
24300 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e  ve path. .** ^On
24310 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
24320 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
24330 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
24340 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
24350 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
24360 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a  e.g. "C:")..**.*
24370 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
24380 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
24390 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
243a0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
243b0 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
243c0 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
243d0 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
243e0 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
243f0 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
24400 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
24410 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
24420 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  ]..** SQLite int
24430 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c  erprets the foll
24440 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72  owing three quer
24450 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
24460 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
24470 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
24480 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
24490 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
244a0 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
244b0 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
244c0 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
244d0 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
244e0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
244f0 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
24500 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
24510 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
24520 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
24530 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
24540 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
24550 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
24560 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
24570 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
24580 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
24590 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
245a0 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
245b0 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
245c0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
245d0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
245e0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
245f0 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
24600 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
24610 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
24620 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
24630 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
24640 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
24650 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
24660 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
24670 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
24680 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
24690 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
246a0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
246b0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
246c0 20 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20   "ro", "rw",.** 
246d0 20 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d      "rwc", or "m
246e0 65 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69  emory". Attempti
246f0 6e 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20  ng to set it to 
24700 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20  any other value 
24710 69 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72  is.**     an err
24720 6f 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49  or)^. .**     ^I
24730 66 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66  f "ro" is specif
24740 69 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61  ied, then the da
24750 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64  tabase is opened
24760 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a   for read-only .
24770 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a  **     access, j
24780 75 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53  ust as if the [S
24790 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
247a0 4e 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65  NLY] flag had be
247b0 65 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a  en set in the .*
247c0 2a 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75  *     third argu
247d0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
247e0 70 72 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49  prepare_v2(). ^I
247f0 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f  f the mode optio
24800 6e 20 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20  n is set to .** 
24810 20 20 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74      "rw", then t
24820 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
24830 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77  pened for read-w
24840 72 69 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72  rite (but not cr
24850 65 61 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63  eate) .**     ac
24860 63 65 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49  cess, as if SQLI
24870 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
24880 45 20 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54  E (but not SQLIT
24890 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68  E_OPEN_CREATE) h
248a0 61 64 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20  ad .**     been 
248b0 73 65 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63  set. ^Value "rwc
248c0 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
248d0 74 6f 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20  to setting both 
248e0 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
248f0 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e  PEN_READWRITE an
24900 64 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  d SQLITE_OPEN_CR
24910 45 41 54 45 2e 20 20 5e 49 66 20 74 68 65 20 6d  EATE.  ^If the m
24920 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a  ode option is.**
24930 20 20 20 20 20 73 65 74 20 74 6f 20 22 6d 65 6d       set to "mem
24940 6f 72 79 22 20 74 68 65 6e 20 61 20 70 75 72 65  ory" then a pure
24950 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61   [in-memory data
24960 62 61 73 65 5d 20 74 68 61 74 20 6e 65 76 65 72  base] that never
24970 20 72 65 61 64 73 0a 2a 2a 20 20 20 20 20 6f 72   reads.**     or
24980 20 77 72 69 74 65 73 20 66 72 6f 6d 20 64 69 73   writes from dis
24990 6b 20 69 73 20 75 73 65 64 2e 20 5e 49 74 20 69  k is used. ^It i
249a0 73 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70  s an error to sp
249b0 65 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f  ecify a value fo
249c0 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 6d 6f 64  r.**     the mod
249d0 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74  e parameter that
249e0 20 69 73 20 6c 65 73 73 20 72 65 73 74 72 69 63   is less restric
249f0 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
24a00 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
24a10 20 20 20 74 68 65 20 66 6c 61 67 73 20 70 61 73     the flags pas
24a20 73 65 64 20 69 6e 20 74 68 65 20 74 68 69 72 64  sed in the third
24a30 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
24a40 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e  lite3_open_v2().
24a50 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62  .**.**   <li> <b
24a60 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e 54 68 65  >cache</b>: ^The
24a70 20 63 61 63 68 65 20 70 61 72 61 6d 65 74 65 72   cache parameter
24a80 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 65   may be set to e
24a90 69 74 68 65 72 20 22 73 68 61 72 65 64 22 20 6f  ither "shared" o
24aa0 72 0a 2a 2a 20 20 20 20 20 22 70 72 69 76 61 74  r.**     "privat
24ab0 65 22 2e 20 5e 53 65 74 74 69 6e 67 20 69 74 20  e". ^Setting it 
24ac0 74 6f 20 22 73 68 61 72 65 64 22 20 69 73 20 65  to "shared" is e
24ad0 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
24ae0 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20 20 20 20  ting the.**     
24af0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
24b00 45 44 43 41 43 48 45 20 62 69 74 20 69 6e 20 74  EDCACHE bit in t
24b10 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
24b20 74 20 70 61 73 73 65 64 20 74 6f 0a 2a 2a 20 20  t passed to.**  
24b30 20 20 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f     sqlite3_open_
24b40 76 32 28 29 2e 20 5e 53 65 74 74 69 6e 67 20 74  v2(). ^Setting t
24b50 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65 74  he cache paramet
24b60 65 72 20 74 6f 20 22 70 72 69 76 61 74 65 22 20  er to "private" 
24b70 69 73 20 0a 2a 2a 20 20 20 20 20 65 71 75 69 76  is .**     equiv
24b80 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
24b90 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
24ba0 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 62 69  _PRIVATECACHE bi
24bb0 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66 20 73 71  t..**     ^If sq
24bc0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
24bd0 69 73 20 75 73 65 64 20 61 6e 64 20 74 68 65 20  is used and the 
24be0 22 63 61 63 68 65 22 20 70 61 72 61 6d 65 74 65  "cache" paramete
24bf0 72 20 69 73 20 70 72 65 73 65 6e 74 20 69 6e 0a  r is present in.
24c00 2a 2a 20 20 20 20 20 61 20 55 52 49 20 66 69 6c  **     a URI fil
24c10 65 6e 61 6d 65 2c 20 69 74 73 20 76 61 6c 75 65  ename, its value
24c20 20 6f 76 65 72 72 69 64 65 73 20 61 6e 79 20 62   overrides any b
24c30 65 68 61 76 69 6f 75 72 20 72 65 71 75 65 73 74  ehaviour request
24c40 65 64 20 62 79 20 73 65 74 74 69 6e 67 0a 2a 2a  ed by setting.**
24c50 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e       SQLITE_OPEN
24c60 5f 50 52 49 56 41 54 45 43 41 43 48 45 20 6f 72  _PRIVATECACHE or
24c70 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41   SQLITE_OPEN_SHA
24c80 52 45 44 43 41 43 48 45 20 66 6c 61 67 2e 0a 2a  REDCACHE flag..*
24c90 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53  * </ul>.**.** ^S
24ca0 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b  pecifying an unk
24cb0 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69  nown parameter i
24cc0 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70  n the query comp
24cd0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69  onent of a URI i
24ce0 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f  s not an.** erro
24cf0 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  r.  Future versi
24d00 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
24d10 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61  ght understand a
24d20 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a  dditional query.
24d30 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ** parameters.  
24d40 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61  See "[query para
24d50 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63  meters with spec
24d60 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53  ial meaning to S
24d70 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61  QLite]" for.** a
24d80 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
24d90 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55  ation..**.** [[U
24da0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
24db0 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66  ples]] <h3>URI f
24dc0 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
24dd0 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62  </h3>.**.** <tab
24de0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c  le border="1" al
24df0 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70  ign=center cellp
24e00 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72  adding=5>.** <tr
24e10 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61  ><th> URI filena
24e20 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73  mes <th> Results
24e30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
24e40 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a  e:data.db <td> .
24e50 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
24e60 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e   the file "data.
24e70 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
24e80 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a  nt directory..**
24e90 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f   <tr><td> file:/
24ea0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
24eb0 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20  b<br>.**        
24ec0 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66    file:///home/f
24ed0 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e  red/data.db <br>
24ee0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
24ef0 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68  le://localhost/h
24f00 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
24f10 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20   <br> <td> .**  
24f20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
24f30 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22   database file "
24f40 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24f50 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  db"..** <tr><td>
24f60 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72   file://darkstar
24f70 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
24f80 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  db <td> .**     
24f90 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22       An error. "
24fa0 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74  darkstar" is not
24fb0 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75   a recognized au
24fc0 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e  thority..** <tr>
24fd0 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65  <td style="white
24fe0 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20  -space:nowrap"> 
24ff0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
25000 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74  e:///C:/Document
25010 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e  s%20and%20Settin
25020 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f  gs/fred/Desktop/
25030 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c  data.db.**     <
25040 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79  td> Windows only
25050 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20  : Open the file 
25060 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65  "data.db" on fre
25070 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64  d's desktop on d
25080 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20  rive.**         
25090 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74   C:. Note that t
250a0 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20  he %20 escaping 
250b0 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20  in this example 
250c0 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  is not strictly 
250d0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63  .**          nec
250e0 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63  essary - space c
250f0 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65  haracters can be
25100 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a   used literally.
25110 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55  **          in U
25120 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a  RI filenames..**
25130 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
25140 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63  ata.db?mode=ro&c
25150 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64  ache=private <td
25160 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  > .**          O
25170 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64  pen file "data.d
25180 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
25190 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20  t directory for 
251a0 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73  read-only access
251b0 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65  ..**          Re
251c0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
251d0 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
251e0 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20  d-cache mode is 
251f0 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20  enabled by.**   
25200 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20         default, 
25210 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61  use a private ca
25220 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  che..** <tr><td>
25230 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64   file:/home/fred
25240 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69  /data.db?vfs=uni
25250 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a  x-nolock <td>.**
25260 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
25270 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
25280 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
25290 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
252a0 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20  nix-nolock"..** 
252b0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
252c0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f  ta.db?mode=reado
252d0 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  nly <td> .**    
252e0 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
252f0 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f  "readonly" is no
25300 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e  t a valid option
25310 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22 20   for the "mode" 
25320 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f  parameter..** </
25330 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52  table>.**.** ^UR
25340 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73  I hexadecimal es
25350 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20 28  cape sequences (
25360 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72 74  %HH) are support
25370 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70 61  ed within the pa
25380 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20  th and.** query 
25390 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20  components of a 
253a0 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69 6d  URI. A hexadecim
253b0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
253c0 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61  ce consists of a
253d0 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67 6e  .** percent sign
253e0 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65   - "%" - followe
253f0 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77 6f  d by exactly two
25400 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69 67   hexadecimal dig
25410 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79 69  its .** specifyi
25420 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c 75  ng an octet valu
25430 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20 70  e. ^Before the p
25440 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f 6d  ath or query com
25450 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20  ponents of a.** 
25460 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72 65  URI filename are
25470 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74 68   interpreted, th
25480 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20 75  ey are encoded u
25490 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20 61  sing UTF-8 and a
254a0 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d  ll .** hexadecim
254b0 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e  al escape sequen
254c0 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79 20  ces replaced by 
254d0 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63 6f  a single byte co
254e0 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20  ntaining the.** 
254f0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63  corresponding oc
25500 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72 6f  tet. If this pro
25510 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20 61  cess generates a
25520 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38 20  n invalid UTF-8 
25530 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65  encoding,.** the
25540 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
25550 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62  efined..**.** <b
25560 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
25570 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65   users:</b>  The
25580 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 66   encoding used f
25590 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  or the filename 
255a0 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73  argument.** of s
255b0 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e  qlite3_open() an
255c0 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  d sqlite3_open_v
255d0 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46 2d  2() must be UTF-
255e0 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72 0a  8, not whatever.
255f0 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20 63  ** codepage is c
25600 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
25610 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e  .  Filenames con
25620 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74  taining internat
25630 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74  ional.** charact
25640 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ers must be conv
25650 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20 70  erted to UTF-8 p
25660 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67 20  rior to passing 
25670 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c  them into.** sql
25680 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
25690 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
256a0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
256b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
256c0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
256d0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
256e0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
256f0 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
25700 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
25710 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
25720 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
25730 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  /.);.SQLITE_API 
25740 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
25750 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64  16(.  const void
25760 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
25770 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
25780 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a 20  me (UTF-16) */. 
25790 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
257a0 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
257b0 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
257c0 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  e */.);.SQLITE_A
257d0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
257e0 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
257f0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
25800 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
25810 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
25820 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
25830 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
25840 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
25850 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
25860 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
25870 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
25880 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
25890 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
258a0 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
258b0 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
258c0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
258d0 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
258e0 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
258f0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74 69  ** These are uti
25900 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20 75  lity routines, u
25910 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70  seful to VFS imp
25920 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68  lementations, th
25930 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73  at check.** to s
25940 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
25950 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
25960 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
25970 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
25980 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
25990 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
259a0 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
259b0 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  at query paramet
259c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69  er..**.** If F i
259d0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
259e0 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20  ilename pointer 
259f0 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
25a00 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f  xOpen() method o
25a10 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c  f .** a VFS impl
25a20 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20  ementation when 
25a30 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  the flags parame
25a40 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20 68  ter to xOpen() h
25a50 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f  as one or .** mo
25a60 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49 54  re of the [SQLIT
25a70 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b  E_OPEN_URI] or [
25a80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
25a90 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61 6e  _DB] bits set an
25aa0 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e 61  d.** P is the na
25ab0 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  me of the query 
25ac0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a  parameter, then.
25ad0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  ** sqlite3_uri_p
25ae0 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
25af0 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65 20  turns the value 
25b00 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72 61  of the P.** para
25b10 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69 73  meter if it exis
25b20 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69  ts or a NULL poi
25b30 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20 6e  nter if P does n
25b40 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20 0a  ot appear as a .
25b50 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
25b60 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20 69  er on F.  If P i
25b70 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d 65  s a query parame
25b80 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20  ter of F.** has 
25b90 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c 75  no explicit valu
25ba0 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  e, then sqlite3_
25bb0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46 2c  uri_parameter(F,
25bc0 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20  P) returns.** a 
25bd0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d  pointer to an em
25be0 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  pty string..**.*
25bf0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72  * The sqlite3_ur
25c00 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
25c10 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65 73   routine assumes
25c20 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f 6f   that P is a boo
25c30 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65  lean.** paramete
25c40 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 72  r and returns tr
25c50 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65 20  ue (1) or false 
25c60 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74 6f  (0) according to
25c70 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66   the value.** of
25c80 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33   P.  The sqlite3
25c90 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50  _uri_boolean(F,P
25ca0 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,B) routine retu
25cb0 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66 20  rns true (1) if 
25cc0 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  the.** value of 
25cd0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
25ce0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65 73  P is one of "yes
25cf0 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22 6f  ", "true", or "o
25d00 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73  n" in any.** cas
25d10 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75  e or if the valu
25d20 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20  e begins with a 
25d30 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e  non-zero number.
25d40 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65    The .** sqlite
25d50 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
25d60 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72 65  P,B) routines re
25d70 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29 20  turns false (0) 
25d80 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 0a  if the value of.
25d90 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ** query paramet
25da0 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22  er P is one of "
25db0 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72  no", "false", or
25dc0 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63 61   "off" in any ca
25dd0 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20  se or.** if the 
25de0 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69 74  value begins wit
25df0 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f  h a numeric zero
25e00 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20 61  .  If P is not a
25e10 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65   query.** parame
25e20 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20 74  ter on F or if t
25e30 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73  he value of P is
25e40 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68 20   does not match 
25e50 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62  any of the.** ab
25e60 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ove, then sqlite
25e70 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
25e80 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42 21  P,B) returns (B!
25e90 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  =0)..**.** The s
25ea0 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
25eb0 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65 20  (F,P,D) routine 
25ec0 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61 6c  converts the val
25ed0 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a  ue of P into a.*
25ee0 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  * 64-bit signed 
25ef0 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74 75  integer and retu
25f00 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65 72  rns that integer
25f10 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65 73  , or D if P does
25f20 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20   not.** exist.  
25f30 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  If the value of 
25f40 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f  P is something o
25f50 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e 74  ther than an int
25f60 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65  eger, then.** ze
25f70 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  ro is returned..
25f80 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20 61  ** .** If F is a
25f90 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
25fa0 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
25fb0 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
25fc0 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a  eturns NULL and.
25fd0 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  ** sqlite3_uri_b
25fe0 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65  oolean(F,P,B) re
25ff0 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20 69  turns B.  If F i
26000 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69  s not a NULL poi
26010 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e  nter and.** is n
26020 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66 69  ot a database fi
26030 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e  le pathname poin
26040 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  ter that SQLite 
26050 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65 20  passed into the 
26060 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74  xOpen.** VFS met
26070 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  hod, then the be
26080 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20 72  havior of this r
26090 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66 69  outine is undefi
260a0 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79  ned and probably
260b0 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  .** undesirable.
260c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .*/.SQLITE_API c
260d0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
260e0 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
260f0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
26100 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
26110 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51 4c  ar *zParam);.SQL
26120 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
26130 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28  te3_uri_boolean(
26140 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
26150 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
26160 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66 61  Param, int bDefa
26170 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ult);.SQLITE_API
26180 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
26190 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36 34  qlite3_uri_int64
261a0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63 6f  (const char*, co
261b0 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69 74  nst char*, sqlit
261c0 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a  e3_int64);.../*.
261d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72  ** CAPI3REF: Err
261e0 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73  or Codes And Mes
261f0 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sages.**.** ^The
26200 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
26210 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
26220 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63  urns the numeric
26230 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f   [result code] o
26240 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
26250 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20  esult code] for 
26260 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
26270 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a  failed sqlite3_*
26280 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73   API call.** ass
26290 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b  ociated with a [
262a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
262b0 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72  ion]. If a prior
262c0 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64   API call failed
262d0 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74  .** but the most
262e0 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c   recent API call
262f0 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20   succeeded, the 
26300 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
26310 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72  m.** sqlite3_err
26320 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69  code() is undefi
26330 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  ned.  ^The sqlit
26340 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63  e3_extended_errc
26350 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  ode().** interfa
26360 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65  ce is the same e
26370 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c  xcept that it al
26380 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65  ways returns the
26390 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72   .** [extended r
263a0 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e  esult code] even
263b0 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72   when extended r
263c0 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a  esult codes are.
263d0 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  ** disabled..**.
263e0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
263f0 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c  errmsg() and sql
26400 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20  ite3_errmsg16() 
26410 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c  return English-l
26420 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20  anguage.** text 
26430 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
26440 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74  he error, as eit
26450 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
26460 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79  -16 respectively
26470 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f  ..** ^(Memory to
26480 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20   hold the error 
26490 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
264a0 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e  s managed intern
264b0 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ally..** The app
264c0 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f  lication does no
264d0 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20  t need to worry 
264e0 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68  about freeing th
264f0 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77  e result..** How
26500 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20  ever, the error 
26510 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20  string might be 
26520 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64  overwritten or d
26530 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a  eallocated by.**
26540 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
26550 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74  s to other SQLit
26560 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63  e interface func
26570 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57  tions.)^.**.** W
26580 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
26590 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
265a0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
265b0 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
265c0 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
265d0 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
265e0 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
265f0 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
26600 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
26610 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
26620 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
26630 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
26640 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
26650 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
26660 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
26670 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
26680 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
26690 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
266a0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
266b0 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
266c0 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
266d0 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
266e0 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
266f0 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
26700 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26710 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
26720 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
26730 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
26740 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
26750 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
26760 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
26770 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
26780 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
26790 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
267a0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
267b0 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
267c0 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
267d0 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
267e0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
267f0 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
26800 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
26810 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
26820 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
26830 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
26840 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
26850 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
26860 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
26870 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
26880 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
26890 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
268a0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
268b0 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
268c0 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
268d0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
268e0 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64  sqlite3_extended
268f0 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33  _errcode(sqlite3
26900 20 2a 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50   *db);.SQLITE_AP
26910 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  I const char *sq
26920 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c  lite3_errmsg(sql
26930 69 74 65 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  ite3*);.SQLITE_A
26940 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  PI const void *s
26950 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28  qlite3_errmsg16(
26960 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
26970 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
26980 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
26990 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
269a0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
269b0 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
269c0 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
269d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
269e0 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
269f0 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
26a00 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
26a10 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
26a20 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
26a30 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
26a40 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
26a50 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
26a60 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
26a70 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
26a80 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
26a90 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
26aa0 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
26ab0 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
26ac0 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
26ad0 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
26ae0 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
26af0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26b00 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
26b10 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
26b20 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
26b30 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
26b40 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
26b50 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
26b60 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
26b70 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
26b80 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
26b90 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
26ba0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
26bb0 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
26bc0 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
26bd0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
26be0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
26bf0 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
26c00 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
26c10 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
26c20 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
26c30 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
26c40 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
26c50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
26c60 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
26c70 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
26c80 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
26c90 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
26ca0 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
26cb0 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
26cc0 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
26cd0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
26ce0 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
26cf0 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
26d00 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
26d10 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28   Limits.**.** ^(
26d20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
26d30 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
26d40 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
26d50 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
26d60 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
26d70 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
26d80 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
26d90 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
26da0 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
26db0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
26dc0 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
26dd0 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
26de0 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
26df0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
26e00 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
26e10 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
26e20 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
26e30 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
26e40 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
26e50 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
26e60 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
26e70 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
26e80 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
26e90 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
26ea0 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
26eb0 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
26ec0 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
26ed0 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
26ee0 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
26ef0 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
26f00 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
26f10 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
26f20 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
26f30 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
26f40 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
26f50 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
26f60 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
26f70 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
26f80 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
26f90 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
26fa0 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
26fb0 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
26fc0 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
26fd0 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
26fe0 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
26ff0 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
27000 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
27010 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
27020 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
27030 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
27040 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
27050 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
27060 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
27070 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
27080 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
27090 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
270a0 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
270b0 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
270c0 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
270d0 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
270e0 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
270f0 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
27100 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
27110 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
27120 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
27130 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
27140 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
27150 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
27160 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
27170 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
27180 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
27190 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
271a0 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
271b0 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
271c0 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
271d0 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
271e0 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
271f0 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
27200 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
27210 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
27220 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
27230 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
27240 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
27250 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
27260 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
27270 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
27280 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
27290 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
272a0 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
272b0 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
272c0 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
272d0 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
272e0 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
272f0 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
27300 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
27310 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
27320 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
27330 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
27340 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
27350 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
27360 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
27370 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
27380 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
27390 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
273a0 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
273b0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
273c0 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
273d0 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
273e0 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
273f0 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
27400 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
27410 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
27420 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
27430 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
27440 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
27450 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
27460 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
27470 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
27480 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
27490 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
274a0 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
274b0 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
274c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
274d0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
274e0 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
274f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27500 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
27510 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
27520 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
27530 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
27540 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
27550 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
27560 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
27570 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
27580 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
27590 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
275a0 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
275b0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
275c0 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
275d0 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
275e0 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
275f0 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
27600 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
27610 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
27620 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
27630 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
27640 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
27650 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
27660 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
27670 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
27680 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
27690 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
276a0 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
276b0 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
276c0 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
276d0 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
276e0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
276f0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
27700 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27710 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
27720 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27730 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
27740 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
27750 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
27760 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
27770 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
27780 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
27790 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
277a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
277b0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
277c0 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
277d0 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
277e0 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
277f0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
27800 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
27810 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
27820 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
27830 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
27840 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
27850 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
27860 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
27870 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
27880 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27890 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
278a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
278b0 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
278c0 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
278d0 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
278e0 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
278f0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
27900 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
27910 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
27920 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
27930 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
27940 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
27950 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
27960 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
27970 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
27980 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
27990 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
279a0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
279b0 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
279c0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
279d0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
279e0 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
279f0 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
27a00 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
27a10 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
27a20 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
27a30 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e   This limit is n
27a40 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  ot currently.** 
27a50 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68  enforced, though
27a60 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61   that might be a
27a70 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74  dded in some fut
27a80 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
27a90 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e  * SQLite.</dd>)^
27aa0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
27ab0 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
27ac0 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  RG]] ^(<dt>SQLIT
27ad0 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
27ae0 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
27af0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
27b00 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
27b10 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
27b20 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
27b30 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
27b40 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  CHED]] ^(<dt>SQL
27b50 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
27b60 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
27b70 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
27b80 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
27b90 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
27ba0 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
27bb0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
27bc0 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
27bd0 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  GTH]].** ^(<dt>S
27be0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
27bf0 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
27c00 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27c10 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
27c20 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
27c30 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
27c40 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
27c50 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
27c60 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
27c70 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
27c80 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28  E_NUMBER]].** ^(
27c90 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
27ca0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
27cb0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
27cc0 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e   maximum index n
27cd0 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61  umber of any [pa
27ce0 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53  rameter] in an S
27cf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a  QL statement.)^.
27d00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
27d10 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
27d20 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
27d30 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
27d40 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
27d50 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
27d60 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
27d70 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
27d80 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
27d90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
27da0 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
27db0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27dc0 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
27dd0 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
27de0 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
27df0 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
27e00 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
27e10 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
27e20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
27e30 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
27e40 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
27e50 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
27e60 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
27e70 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
27e80 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
27e90 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
27ea0 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
27eb0 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
27ec0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
27ed0 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
27ee0 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
27ef0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
27f00 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
27f10 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
27f20 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
27f30 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
27f40 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
27f50 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
27f60 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
27f70 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
27f80 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
27f90 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
27fa0 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a            10../*
27fb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
27fc0 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
27fd0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
27fe0 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
27ff0 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
28000 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
28010 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
28020 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
28030 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
28040 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
28050 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
28060 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
28070 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
28080 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
28090 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
280a0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
280b0 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
280c0 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
280d0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
280e0 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
280f0 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
28100 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
28110 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
28120 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
28130 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
28140 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
28150 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
28160 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
28170 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
28180 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
28190 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
281a0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
281b0 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
281c0 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
281d0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
281e0 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
281f0 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
28200 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
28210 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
28220 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
28230 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
28240 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
28250 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
28260 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
28270 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
28280 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
28290 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
282a0 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
282b0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
282c0 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
282d0 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
282e0 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
282f0 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
28300 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
28310 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
28320 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
28330 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
28340 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
28350 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
28360 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
28370 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
28380 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
28390 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
283a0 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
283b0 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
283c0 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
283d0 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
283e0 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
283f0 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
28400 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
28410 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
28420 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
28430 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
28440 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
28450 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
28460 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
28470 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
28480 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
28490 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69  tor bytes as thi
284a0 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66  s saves SQLite f
284b0 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a  rom having to.**
284c0 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
284d0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
284e0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
284f0 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
28500 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
28510 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
28520 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
28530 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
28540 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
28550 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
28560 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
28570 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
28580 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
28590 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
285a0 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
285b0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
285c0 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
285d0 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
285e0 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
285f0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
28600 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
28610 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
28620 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
28630 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
28640 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
28650 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
28660 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
28670 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
28680 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
28690 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
286a0 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
286b0 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
286c0 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
286d0 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
286e0 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
286f0 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
28700 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
28710 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
28720 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
28730 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
28740 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
28750 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
28760 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
28770 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
28780 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
28790 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
287a0 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
287b0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
287c0 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
287d0 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
287e0 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
287f0 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
28800 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
28810 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
28820 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28830 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
28840 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
28850 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
28860 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
28870 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
28880 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
28890 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
288a0 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
288b0 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
288c0 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
288d0 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
288e0 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
288f0 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
28900 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
28910 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
28920 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
28930 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
28940 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
28950 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
28960 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
28970 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
28980 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
28990 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
289a0 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
289b0 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
289c0 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
289d0 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
289e0 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
289f0 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
28a00 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
28a10 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
28a20 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
28a30 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
28a40 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
28a50 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
28a60 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
28a70 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
28a80 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
28a90 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a   run it again..*
28aa0 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
28ab0 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
28ac0 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
28ad0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
28ae0 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
28af0 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
28b00 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
28b10 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
28b20 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
28b30 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
28b40 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
28b50 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
28b60 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
28b70 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
28b80 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
28b90 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
28ba0 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
28bb0 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
28bc0 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
28bd0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
28be0 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
28bf0 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
28c00 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
28c10 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
28c20 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
28c30 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
28c40 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
28c50 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
28c60 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
28c70 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
28c80 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
28c90 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
28ca0 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
28cb0 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
28cc0 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
28cd0 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
28ce0 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
28cf0 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
28d00 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
28d10 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
28d20 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
28d30 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
28d40 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
28d50 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
28d60 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
28d70 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
28d80 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
28d90 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
28da0 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
28db0 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
28dc0 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
28dd0 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
28de0 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
28df0 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
28e00 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
28e10 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
28e20 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
28e30 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
28e40 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
28e50 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
28e60 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
28e70 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
28e80 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
28e90 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
28ea0 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
28eb0 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
28ec0 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
28ed0 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
28ee0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
28ef0 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
28f00 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
28f10 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68  s enabled..** th
28f20 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  e .** </li>.** <
28f30 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  /ol>.*/.SQLITE_A
28f40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
28f50 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
28f60 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
28f70 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
28f80 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
28f90 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
28fa0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
28fb0 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
28fc0 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
28fd0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
28fe0 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
28ff0 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
29000 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
29010 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
29020 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
29030 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
29040 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
29050 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
29060 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
29070 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
29080 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
29090 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
290a0 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
290b0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
290c0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
290d0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
290e0 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
290f0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
29100 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
29110 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
29120 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
29130 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
29140 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
29150 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
29160 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
29170 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
29180 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
29190 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
291a0 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
291b0 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
291c0 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
291d0 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
291e0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
291f0 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
29200 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
29210 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
29220 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
29230 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
29240 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
29250 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
29260 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
29270 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
29280 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
29290 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
292a0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
292b0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
292c0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
292d0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
292e0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
292f0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
29300 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
29310 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
29320 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
29330 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
29340 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
29350 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
29360 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
29370 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
29380 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
29390 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
293a0 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
293b0 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
293c0 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
293d0 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
293e0 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
293f0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
29400 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
29410 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
29420 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
29430 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
29440 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
29450 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
29460 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
29470 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
29480 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
29490 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
294a0 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
294b0 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
294c0 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
294d0 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
294e0 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
294f0 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
29500 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
29510 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29520 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
29530 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
29540 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
29550 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
29560 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
29570 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
29580 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  2()]..*/.SQLITE_
29590 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
295a0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
295b0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
295c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
295d0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
295e0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
295f0 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
29600 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  base.**.** ^The 
29610 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
29620 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
29630 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
29640 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
29650 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
29660 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29670 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
29680 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
29690 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
296a0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
296b0 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
296c0 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
296d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
296e0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
296f0 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
29700 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
29710 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
29720 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
29730 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
29740 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
29750 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
29760 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
29770 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
29780 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
29790 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
297a0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
297b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
297c0 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
297d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
297e0 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
297f0 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
29800 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
29810 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
29820 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
29830 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
29840 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
29850 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
29860 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
29870 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
29880 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
29890 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
298a0 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
298b0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
298c0 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
298d0 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
298e0 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
298f0 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
29900 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
29910 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
29920 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
29930 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
29940 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
29950 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
29960 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
29970 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
29980 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
29990 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
299a0 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
299b0 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
299c0 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
299d0 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
299e0 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
299f0 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
29a00 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
29a10 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
29a20 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
29a30 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
29a40 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
29a50 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
29a60 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
29a70 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
29a80 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
29a90 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
29aa0 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
29ab0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
29ac0 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
29ad0 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
29ae0 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
29af0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
29b00 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
29b10 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
29b20 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
29b30 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
29b40 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
29b50 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
29b60 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
29b70 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
29b80 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
29b90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
29ba0 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
29bb0 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
29bc0 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
29bd0 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
29be0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
29bf0 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
29c00 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
29c10 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
29c20 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
29c30 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f  t has not run to
29c40 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f   completion and/
29c50 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62  or has not .** b
29c60 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
29c70 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
29c80 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
29c90 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
29ca0 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
29cb0 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
29cc0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
29cd0 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
29ce0 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
29cf0 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
29d00 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
29d10 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
29d20 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
29d30 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
29d40 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
29d50 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
29d60 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
29d70 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
29d80 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
29d90 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
29da0 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
29db0 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
29dc0 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
29dd0 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
29de0 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
29df0 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
29e00 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
29e10 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
29e20 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
29e30 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
29e40 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
29e50 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
29e60 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
29e70 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
29e80 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
29e90 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
29ea0 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  open..*/.SQLITE_
29eb0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
29ec0 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65  stmt_busy(sqlite
29ed0 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
29ee0 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
29ef0 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
29f00 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
29f10 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
29f20 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
29f30 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
29f40 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
29f50 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
29f60 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
29f70 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
29f80 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
29f90 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
29fa0 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
29fb0 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
29fc0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
29fd0 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
29fe0 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
29ff0 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
2a000 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
2a010 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
2a020 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
2a030 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2a040 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
2a050 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
2a060 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
2a070 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
2a080 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
2a090 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
2a0a0 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
2a0b0 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
2a0c0 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
2a0d0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
2a0e0 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
2a0f0 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
2a100 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
2a110 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
2a120 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2a130 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
2a140 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
2a150 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
2a160 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
2a170 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
2a180 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
2a190 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
2a1a0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2a1b0 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
2a1c0 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
2a1d0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
2a1e0 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
2a1f0 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
2a200 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
2a210 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
2a220 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
2a230 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2a240 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
2a250 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
2a260 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
2a270 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2a280 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
2a290 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2a2a0 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
2a2b0 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
2a2c0 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
2a2d0 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
2a2e0 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
2a2f0 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
2a300 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
2a310 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
2a320 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
2a330 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
2a340 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
2a350 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
2a360 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2a370 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
2a380 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
2a390 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
2a3a0 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
2a3b0 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
2a3c0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2a3d0 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
2a3e0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
2a3f0 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
2a400 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
2a410 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
2a420 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
2a430 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
2a440 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
2a450 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
2a460 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2a470 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2a480 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2a490 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2a4a0 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
2a4b0 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
2a4c0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
2a4d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2a4e0 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
2a4f0 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
2a500 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
2a510 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2a520 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
2a530 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2a540 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
2a550 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
2a560 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2a570 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2a580 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2a590 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
2a5a0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
2a5b0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2a5c0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
2a5d0 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2a5e0 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
2a5f0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2a600 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2a610 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
2a620 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2a630 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
2a640 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
2a650 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
2a660 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2a670 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2a680 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
2a690 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2a6a0 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
2a6b0 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
2a6c0 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
2a6d0 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
2a6e0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
2a6f0 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
2a700 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
2a710 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
2a720 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
2a730 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2a740 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
2a750 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
2a760 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
2a770 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
2a780 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
2a790 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2a7a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
2a7b0 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2a7c0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2a7d0 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2a7e0 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
2a7f0 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
2a800 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
2a810 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2a820 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
2a830 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
2a840 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
2a850 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
2a860 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
2a870 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
2a880 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2a890 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
2a8a0 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2a8b0 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
2a8c0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2a8d0 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
2a8e0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2a8f0 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
2a900 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
2a910 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
2a920 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
2a930 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
2a940 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
2a950 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
2a960 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
2a970 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2a980 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
2a990 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
2a9a0 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
2a9b0 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
2a9c0 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e  binding}.**.** ^
2a9d0 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
2a9e0 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
2a9f0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
2aa00 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
2aa10 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
2aa20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
2aa30 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
2aa40 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
2aa50 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
2aa60 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
2aa70 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
2aa80 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
2aa90 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
2aaa0 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
2aab0 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
2aac0 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
2aad0 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
2aae0 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
2aaf0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
2ab00 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
2ab10 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
2ab20 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
2ab30 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
2ab40 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
2ab50 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
2ab60 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
2ab70 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
2ab80 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
2ab90 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
2aba0 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
2abb0 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
2abc0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2abd0 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
2abe0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2abf0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2ac00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2ac10 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
2ac20 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
2ac30 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2ac40 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
2ac50 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
2ac60 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2ac70 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
2ac80 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
2ac90 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2aca0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2acb0 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
2acc0 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
2acd0 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
2ace0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
2acf0 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
2ad00 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
2ad10 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
2ad20 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
2ad30 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
2ad40 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2ad50 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
2ad60 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
2ad70 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
2ad80 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
2ad90 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
2ada0 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
2adb0 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
2adc0 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
2add0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2ade0 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2adf0 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
2ae00 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
2ae10 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
2ae20 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
2ae30 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
2ae40 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
2ae50 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
2ae60 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
2ae70 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
2ae80 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
2ae90 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2aea0 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
2aeb0 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
2aec0 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2aed0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
2aee0 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
2aef0 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
2af00 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
2af10 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
2af20 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
2af30 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
2af40 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2af50 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2af60 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
2af70 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
2af80 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2af90 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
2afa0 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
2afb0 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
2afc0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2afd0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
2afe0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2aff0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2b000 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2b010 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2b020 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2b030 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
2b040 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
2b050 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2b060 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
2b070 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2b080 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
2b090 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2b0a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2b0b0 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
2b0c0 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
2b0d0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2b0e0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2b0f0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
2b100 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2b110 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
2b120 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2b130 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2b140 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74  _bind_text16() t
2b150 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74  hen that paramet
2b160 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
2b170 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
2b180 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
2b190 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
2b1a0 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
2b1b0 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
2b1c0 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
2b1d0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
2b1e0 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
2b1f0 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
2b200 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
2b210 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
2b220 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
2b230 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
2b240 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
2b250 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
2b260 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
2b270 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
2b280 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
2b290 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
2b2a0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
2b2b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2b2c0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
2b2d0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2b2e0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
2b2f0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2b300 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
2b310 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
2b320 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
2b330 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
2b340 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
2b350 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
2b360 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
2b370 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
2b380 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2b390 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
2b3a0 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2b3b0 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
2b3c0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73  if the call to s
2b3d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b3e0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  (),.** sqlite3_b
2b3f0 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73  ind_text(), or s
2b400 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2b410 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a  16() fails.  .**
2b420 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2b430 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
2b440 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2b450 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
2b460 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
2b470 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
2b480 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2b490 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
2b4a0 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
2b4b0 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2b4c0 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
2b4d0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2b4e0 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
2b4f0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
2b500 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
2b510 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
2b520 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2b530 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
2b540 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
2b550 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
2b560 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
2b570 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2b580 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2b590 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
2b5a0 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
2b5b0 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
2b5c0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
2b5d0 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
2b5e0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
2b5f0 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
2b600 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
2b610 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
2b620 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
2b630 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
2b640 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
2b650 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
2b660 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
2b670 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2b680 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
2b690 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
2b6a0 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
2b6b0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
2b6c0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
2b6d0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
2b6e0 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
2b6f0 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
2b700 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
2b710 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
2b720 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
2b730 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
2b740 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2b750 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
2b760 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
2b770 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
2b780 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2b790 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
2b7a0 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
2b7b0 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
2b7c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2b7d0 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
2b7e0 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
2b7f0 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
2b800 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
2b810 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
2b820 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2b830 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
2b840 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
2b850 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
2b860 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
2b870 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2b880 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2b890 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
2b8a0 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2b8b0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
2b8c0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
2b8d0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
2b8e0 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
2b8f0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2b900 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
2b910 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
2b920 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
2b930 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
2b940 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2b950 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
2b960 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
2b970 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
2b980 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
2b990 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
2b9a0 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
2b9b0 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
2b9c0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
2b9d0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
2b9e0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2b9f0 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
2ba00 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
2ba10 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
2ba20 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2ba30 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2ba40 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2ba50 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2ba60 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2ba70 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
2ba80 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2ba90 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2baa0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2bab0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2bac0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2bad0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2bae0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2baf0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2bb00 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2bb10 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
2bb20 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2bb30 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54  , double);.SQLIT
2bb40 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2bb50 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
2bb60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2bb70 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2bb80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2bb90 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2bba0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2bbb0 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  e3_int64);.SQLIT
2bbc0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2bbd0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
2bbe0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2bbf0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2bc00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2bc10 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2bc20 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
2bc30 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2bc40 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2bc50 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2bc60 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
2bc70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2bc80 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2bc90 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2bca0 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2bcb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2bcc0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2bcd0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2bce0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2bcf0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2bd00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2bd10 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
2bd20 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
2bd30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2bd40 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
2bd50 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  L Parameters.**.
2bd60 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
2bd70 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2bd80 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
2bd90 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
2bda0 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
2bdb0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2bdc0 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
2bdd0 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
2bde0 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
2bdf0 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
2be00 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
2be10 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
2be20 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
2be30 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
2be40 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
2be50 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
2be60 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
2be70 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
2be80 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
2be90 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
2bea0 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
2beb0 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
2bec0 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
2bed0 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
2bee0 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
2bef0 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
2bf00 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
2bf10 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
2bf20 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
2bf30 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
2bf40 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
2bf50 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
2bf60 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
2bf70 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
2bf80 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
2bf90 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2bfa0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2bfb0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2bfc0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2bfd0 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2bfe0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2bff0 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2c000 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
2c010 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2c020 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2c030 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2c040 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2c050 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
2c060 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
2c070 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c080 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2c090 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
2c0a0 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
2c0b0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2c0c0 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
2c0d0 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
2c0e0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c0f0 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
2c100 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2c110 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
2c120 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
2c130 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
2c140 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
2c150 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
2c160 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
2c170 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
2c180 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2c190 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
2c1a0 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
2c1b0 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
2c1c0 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
2c1d0 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
2c1e0 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
2c1f0 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
2c200 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
2c210 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
2c220 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
2c230 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
2c240 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
2c250 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
2c260 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
2c270 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
2c280 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
2c290 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2c2a0 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
2c2b0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2c2c0 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
2c2d0 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
2c2e0 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
2c2f0 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
2c300 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
2c310 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
2c320 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2c330 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
2c340 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
2c350 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
2c360 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
2c370 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
2c380 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
2c390 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
2c3a0 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
2c3b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c3c0 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2c3d0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2c3e0 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2c3f0 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2c400 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2c410 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2c420 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2c430 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2c440 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2c450 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2c460 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
2c470 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2c480 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c490 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2c4a0 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
2c4b0 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
2c4c0 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a  A Given Name.**.
2c4d0 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2c4e0 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2c4f0 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2c500 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2c510 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2c520 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2c530 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2c540 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2c550 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2c560 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2c570 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2c580 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2c590 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2c5a0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2c5b0 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2c5c0 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2c5d0 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2c5e0 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2c5f0 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2c600 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2c610 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2c620 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2c630 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2c640 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2c650 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2c660 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2c670 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2c680 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2c690 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2c6a0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2c6b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2c6c0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2c6d0 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2c6e0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2c6f0 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
2c700 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
2c710 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
2c720 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2c730 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
2c740 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
2c750 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  tement.**.** ^Co
2c760 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
2c770 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
2c780 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c790 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
2c7a0 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
2c7b0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
2c7c0 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
2c7d0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c7e0 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
2c7f0 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
2c800 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
2c810 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
2c820 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2c830 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
2c840 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2c850 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2c860 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2c870 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
2c880 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
2c890 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
2c8a0 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2c8b0 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2c8c0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
2c8d0 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2c8e0 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
2c8f0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2c900 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
2c910 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
2c920 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
2c930 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
2c940 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
2c950 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
2c960 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
2c970 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
2c980 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2c990 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2c9a0 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2c9b0 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2c9c0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
2c9d0 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
2c9e0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult Set.**.** ^T
2c9f0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2ca00 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
2ca10 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
2ca20 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
2ca30 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
2ca40 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
2ca50 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
2ca60 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2ca70 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
2ca80 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2ca90 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2caa0 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2cab0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
2cac0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2cad0 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
2cae0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2caf0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
2cb00 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
2cb10 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
2cb20 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
2cb30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cb40 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
2cb50 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
2cb60 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
2cb70 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2cb80 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
2cb90 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
2cba0 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2cbb0 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
2cbc0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
2cbd0 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
2cbe0 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
2cbf0 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
2cc00 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cc10 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
2cc20 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2cc30 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
2cc40 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
2cc50 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2cc60 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
2cc70 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
2cc80 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2cc90 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
2cca0 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
2ccb0 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
2ccc0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2ccd0 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2cce0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2ccf0 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
2cd00 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
2cd10 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
2cd20 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
2cd30 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
2cd40 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
2cd50 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
2cd60 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
2cd70 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
2cd80 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
2cd90 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
2cda0 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2cdb0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2cdc0 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
2cdd0 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
2cde0 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
2cdf0 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
2ce00 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
2ce10 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
2ce20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
2ce30 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
2ce40 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
2ce50 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
2ce60 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
2ce70 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
2ce80 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
2ce90 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
2cea0 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c  the next..*/.SQL
2ceb0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2cec0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2ced0 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
2cee0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  stmt*, int N);.S
2cef0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2cf00 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2cf10 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
2cf20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2cf30 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2cf40 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
2cf50 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
2cf60 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
2cf70 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
2cf80 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
2cf90 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
2cfa0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2cfb0 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
2cfc0 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
2cfd0 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
2cfe0 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
2cff0 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
2d000 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
2d010 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2d020 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
2d030 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
2d040 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
2d050 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
2d060 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2d070 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
2d080 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
2d090 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
2d0a0 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
2d0b0 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
2d0c0 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
2d0d0 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
2d0e0 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
2d0f0 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
2d100 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
2d110 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2d120 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
2d130 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2d140 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
2d150 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
2d160 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d170 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2d180 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2d190 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2d1a0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2d1b0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2d1c0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2d1d0 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2d1e0 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2d1f0 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
2d200 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
2d210 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
2d220 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
2d230 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
2d240 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
2d250 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
2d260 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
2d270 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
2d280 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2d290 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2d2a0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2d2b0 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
2d2c0 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
2d2d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d2e0 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
2d2f0 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
2d300 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
2d310 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
2d320 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2d330 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
2d340 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
2d350 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2d360 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
2d370 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
2d380 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
2d390 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
2d3a0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
2d3b0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
2d3c0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
2d3d0 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
2d3e0 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
2d3f0 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
2d400 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
2d410 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
2d420 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2d430 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
2d440 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
2d450 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
2d460 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
2d470 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2d480 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
2d490 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
2d4a0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2d4b0 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
2d4c0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2d4d0 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
2d4e0 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
2d4f0 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
2d500 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
2d510 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
2d520 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
2d530 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
2d540 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
2d550 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
2d560 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
2d570 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
2d580 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2d590 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
2d5a0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
2d5b0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2d5c0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2d5d0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2d5e0 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2d5f0 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2d600 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2d610 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
2d620 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2d630 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2d640 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
2d650 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
2d660 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
2d670 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d680 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
2d690 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2d6a0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2d6b0 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
2d6c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2d6d0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2d6e0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
2d6f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2d700 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2d710 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
2d720 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
2d730 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
2d740 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d750 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
2d760 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
2d770 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2d780 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2d790 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c  ndefined..*/.SQL
2d7a0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2d7b0 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2d7c0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2d7d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2d7e0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2d7f0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2d800 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2d810 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
2d820 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2d830 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2d840 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2d850 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
2d860 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2d870 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2d880 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d890 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2d8a0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2d8b0 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2d8c0 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2d8d0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2d8e0 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
2d8f0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2d900 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2d910 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2d920 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2d930 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2d940 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2d950 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
2d960 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
2d970 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2d980 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
2d990 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
2d9a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d9b0 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
2d9c0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
2d9d0 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2d9e0 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
2d9f0 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
2da00 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
2da10 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
2da20 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
2da30 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
2da40 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2da50 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
2da60 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
2da70 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
2da80 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
2da90 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
2daa0 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2dab0 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
2dac0 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
2dad0 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
2dae0 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
2daf0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2db00 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2db10 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
2db20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
2db30 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
2db40 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
2db50 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
2db60 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
2db70 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
2db80 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
2db90 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
2dba0 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
2dbb0 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
2dbc0 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
2dbd0 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
2dbe0 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
2dbf0 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
2dc00 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
2dc10 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
2dc20 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
2dc30 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
2dc40 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
2dc50 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
2dc60 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
2dc70 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
2dc80 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
2dc90 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
2dca0 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
2dcb0 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
2dcc0 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
2dcd0 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
2dce0 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
2dcf0 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
2dd00 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
2dd10 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
2dd20 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
2dd30 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
2dd40 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
2dd50 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
2dd60 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
2dd70 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
2dd80 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
2dd90 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
2dda0 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
2ddb0 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
2ddc0 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
2ddd0 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lues..*/.SQLITE_
2dde0 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2ddf0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2de00 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2de10 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2de20 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2de30 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2de40 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
2de50 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2de60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2de70 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
2de80 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
2de90 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
2dea0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
2deb0 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
2dec0 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
2ded0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2dee0 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2def0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2df00 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
2df10 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2df20 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
2df30 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
2df40 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2df50 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
2df60 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
2df70 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2df80 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
2df90 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2dfa0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
2dfb0 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
2dfc0 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
2dfd0 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
2dfe0 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
2dff0 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
2e000 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
2e010 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
2e020 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
2e030 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
2e040 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2e050 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e060 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
2e070 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
2e080 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
2e090 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2e0a0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2e0b0 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
2e0c0 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
2e0d0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2e0e0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
2e0f0 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
2e100 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
2e110 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2e120 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
2e130 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
2e140 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
2e150 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
2e160 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2e170 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
2e180 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
2e190 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
2e1a0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
2e1b0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
2e1c0 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2e1d0 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
2e1e0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
2e1f0 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
2e200 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
2e210 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
2e220 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
2e230 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
2e240 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
2e250 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
2e260 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
2e270 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
2e280 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
2e290 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
2e2a0 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
2e2b0 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
2e2c0 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
2e2d0 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
2e2e0 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
2e2f0 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
2e300 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2e310 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
2e320 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
2e330 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
2e340 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
2e350 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
2e360 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
2e370 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
2e380 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
2e390 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
2e3a0 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2e3b0 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
2e3c0 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
2e3d0 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
2e3e0 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
2e3f0 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
2e400 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
2e410 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
2e420 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2e430 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2e440 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
2e450 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2e460 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
2e470 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2e480 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
2e490 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
2e4a0 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
2e4b0 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2e4c0 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
2e4d0 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2e4e0 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
2e4f0 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
2e500 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
2e510 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
2e520 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
2e530 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
2e540 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
2e550 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
2e560 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
2e570 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
2e580 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
2e590 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2e5a0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
2e5b0 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
2e5c0 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
2e5d0 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
2e5e0 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
2e5f0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
2e600 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
2e610 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
2e620 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
2e630 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
2e640 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
2e650 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2e660 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2e670 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
2e680 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
2e690 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
2e6a0 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
2e6b0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
2e6c0 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
2e6d0 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2e6e0 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
2e6f0 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2e700 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
2e710 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
2e720 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
2e730 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
2e740 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
2e750 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
2e760 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
2e770 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2e780 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
2e790 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2e7a0 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
2e7b0 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2e7c0 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
2e7d0 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2e7e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
2e7f0 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
2e800 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
2e810 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
2e820 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
2e830 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
2e840 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
2e850 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
2e860 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
2e870 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2e880 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2e890 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
2e8a0 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
2e8b0 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
2e8c0 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
2e8d0 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
2e8e0 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
2e8f0 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
2e900 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
2e910 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
2e920 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
2e930 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2e940 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
2e950 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
2e960 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
2e970 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
2e980 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
2e990 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
2e9a0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2e9b0 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
2e9c0 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
2e9d0 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2e9e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
2e9f0 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
2ea00 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
2ea10 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
2ea20 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
2ea30 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
2ea40 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
2ea50 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
2ea60 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2ea70 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
2ea80 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2ea90 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
2eaa0 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
2eab0 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
2eac0 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
2ead0 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
2eae0 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
2eaf0 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
2eb00 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
2eb10 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
2eb20 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
2eb30 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2eb40 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
2eb50 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
2eb60 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
2eb70 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
2eb80 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
2eb90 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
2eba0 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
2ebb0 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
2ebc0 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
2ebd0 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
2ebe0 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
2ebf0 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
2ec00 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
2ec10 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
2ec20 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
2ec30 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
2ec40 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2ec50 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
2ec60 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
2ec70 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
2ec80 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
2ec90 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
2eca0 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
2ecb0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2ecc0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
2ecd0 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
2ece0 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
2ecf0 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
2ed00 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2ed10 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
2ed20 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
2ed30 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
2ed40 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
2ed50 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
2ed60 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
2ed70 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2ed80 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2ed90 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
2eda0 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
2edb0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2edc0 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
2edd0 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
2ede0 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
2edf0 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
2ee00 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
2ee10 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
2ee20 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
2ee30 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
2ee40 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
2ee50 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
2ee60 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
2ee70 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
2ee80 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
2ee90 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2eea0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2eeb0 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
2eec0 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
2eed0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2eee0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2eef0 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
2ef00 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
2ef10 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
2ef20 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2ef30 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
2ef40 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
2ef50 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2ef60 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
2ef70 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2ef80 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
2ef90 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2efa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
2efb0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2efc0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2efd0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2efe0 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
2eff0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f000 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2f010 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f020 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2f030 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
2f040 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
2f050 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2f060 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2f070 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2f080 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
2f090 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
2f0a0 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
2f0b0 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
2f0c0 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
2f0d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2f0e0 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
2f0f0 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
2f100 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
2f110 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
2f120 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
2f130 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
2f140 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2f150 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
2f160 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
2f170 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2f180 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2f190 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2f1a0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2f1b0 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
2f1c0 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
2f1d0 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2f1e0 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2f1f0 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
2f200 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2f210 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
2f220 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
2f230 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
2f240 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2f250 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
2f260 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
2f270 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
2f280 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
2f290 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
2f2a0 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
2f2b0 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
2f2c0 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
2f2d0 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
2f2e0 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
2f2f0 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
2f300 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
2f310 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2f320 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2f330 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
2f340 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
2f350 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2f360 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2f370 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2f380 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
2f390 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2f3a0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
2f3b0 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
2f3c0 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
2f3d0 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
2f3e0 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
2f3f0 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2f400 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
2f410 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
2f420 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
2f430 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2f440 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
2f450 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
2f460 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
2f470 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
2f480 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
2f490 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
2f4a0 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
2f4b0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2f4c0 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
2f4d0 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
2f4e0 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
2f4f0 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
2f500 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
2f510 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
2f520 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
2f530 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
2f540 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
2f550 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
2f560 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
2f570 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
2f580 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
2f590 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
2f5a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2f5b0 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
2f5c0 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
2f5d0 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2f5e0 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
2f5f0 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
2f600 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
2f610 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
2f620 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
2f630 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
2f640 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
2f650 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
2f660 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
2f670 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f680 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
2f690 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
2f6a0 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
2f6b0 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2f6c0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2f6d0 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
2f6e0 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
2f6f0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2f700 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2f710 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2f720 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
2f730 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
2f740 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
2f750 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
2f760 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
2f770 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
2f780 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2f790 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
2f7a0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2f7b0 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
2f7c0 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
2f7d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
2f7e0 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2f7f0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2f800 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2f810 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
2f820 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
2f830 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2f840 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2f850 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
2f860 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
2f870 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
2f880 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
2f890 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
2f8a0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2f8b0 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
2f8c0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
2f8d0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2f8e0 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
2f8f0 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
2f900 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
2f910 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
2f920 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
2f930 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2f940 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
2f950 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
2f960 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
2f970 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
2f980 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
2f990 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
2f9a0 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
2f9b0 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
2f9c0 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
2f9d0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2f9e0 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2f9f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2fa00 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2fa10 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
2fa20 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
2fa30 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
2fa40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2fa50 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
2fa60 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
2fa70 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
2fa80 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
2fa90 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
2faa0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2fab0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
2fac0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
2fad0 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
2fae0 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
2faf0 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
2fb00 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2fb10 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
2fb20 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
2fb30 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
2fb40 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
2fb50 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2fb60 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
2fb70 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
2fb80 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
2fb90 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
2fba0 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
2fbb0 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
2fbc0 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
2fbd0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
2fbe0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2fbf0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2fc00 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
2fc10 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
2fc20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
2fc30 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
2fc40 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
2fc50 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
2fc60 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
2fc70 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
2fc80 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
2fc90 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
2fca0 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
2fcb0 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
2fcc0 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
2fcd0 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
2fce0 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
2fcf0 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
2fd00 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2fd10 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
2fd20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
2fd30 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
2fd40 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
2fd50 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
2fd60 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
2fd70 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
2fd80 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
2fd90 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
2fda0 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
2fdb0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
2fdc0 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
2fdd0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
2fde0 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
2fdf0 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
2fe00 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
2fe10 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
2fe20 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
2fe30 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2fe40 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
2fe50 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
2fe60 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
2fe70 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
2fe80 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
2fe90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
2fea0 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
2feb0 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
2fec0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2fed0 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
2fee0 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2fef0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
2ff00 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
2ff10 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
2ff20 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
2ff30 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2ff40 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
2ff50 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
2ff60 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
2ff70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2ff80 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
2ff90 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
2ffa0 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
2ffb0 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
2ffc0 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
2ffd0 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
2ffe0 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2fff0 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
30000 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
30010 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
30020 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30030 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
30040 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
30050 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
30060 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
30070 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
30080 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
30090 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
300a0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
300b0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
300c0 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
300d0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
300e0 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
300f0 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
30100 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
30110 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
30120 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
30130 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
30140 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
30150 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
30160 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
30170 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
30180 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
30190 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
301a0 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
301b0 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
301c0 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
301d0 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
301e0 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
301f0 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
30200 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
30210 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
30220 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
30230 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
30240 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
30250 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
30260 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
30270 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
30280 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30290 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
302a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
302b0 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
302c0 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
302d0 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
302e0 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
302f0 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
30300 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
30310 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
30320 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
30330 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
30340 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
30350 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
30360 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
30370 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
30380 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
30390 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
303a0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
303b0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
303c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
303d0 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
303e0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
303f0 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
30400 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
30410 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
30420 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
30430 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
30440 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
30450 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
30460 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
30470 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
30480 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
30490 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
304a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
304b0 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
304c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
304d0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
304e0 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
304f0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30500 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
30510 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
30520 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
30530 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
30540 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
30550 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
30560 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
30570 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30580 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
30590 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
305a0 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
305b0 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
305c0 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
305d0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
305e0 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
305f0 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
30600 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30610 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
30620 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
30630 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
30640 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
30650 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
30660 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
30670 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
30680 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
30690 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
306a0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
306b0 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
306c0 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
306d0 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
306e0 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
306f0 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
30700 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
30710 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
30720 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
30730 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
30740 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
30750 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
30760 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
30770 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
30780 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
30790 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
307a0 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
307b0 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
307c0 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
307d0 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
307e0 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
307f0 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
30800 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
30810 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
30820 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
30830 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
30840 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
30850 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
30860 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
30870 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
30880 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
30890 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
308a0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
308b0 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
308c0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
308d0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
308e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
308f0 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
30900 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
30910 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
30920 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
30930 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
30940 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
30950 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
30960 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
30970 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
30980 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
30990 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
309a0 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
309b0 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
309c0 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
309d0 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
309e0 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
309f0 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
30a00 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
30a10 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
30a20 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
30a30 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
30a40 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
30a50 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
30a60 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
30a70 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
30a80 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
30a90 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
30aa0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
30ab0 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
30ac0 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
30ad0 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
30ae0 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
30af0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
30b00 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
30b10 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
30b20 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
30b30 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
30b40 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
30b50 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
30b60 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
30b70 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
30b80 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
30b90 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
30ba0 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
30bb0 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
30bc0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
30bd0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
30be0 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
30bf0 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
30c00 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
30c10 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
30c20 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
30c30 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
30c40 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
30c50 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
30c60 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
30c70 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
30c80 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
30c90 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
30ca0 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
30cb0 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
30cc0 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
30cd0 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
30ce0 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
30cf0 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
30d00 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
30d10 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
30d20 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
30d30 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
30d40 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
30d50 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
30d60 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
30d70 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
30d80 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
30d90 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
30da0 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
30db0 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
30dc0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
30dd0 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
30de0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
30df0 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
30e00 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
30e10 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
30e20 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
30e30 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
30e40 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
30e50 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
30e60 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
30e70 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
30e80 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
30e90 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
30ea0 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
30eb0 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
30ec0 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
30ed0 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
30ee0 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
30ef0 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
30f00 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
30f10 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
30f20 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
30f30 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
30f40 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
30f50 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
30f60 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
30f70 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
30f80 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
30f90 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
30fa0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
30fb0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
30fc0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
30fd0 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
30fe0 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
30ff0 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
31000 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
31010 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
31020 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
31030 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
31040 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
31050 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
31060 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
31070 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
31080 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
31090 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
310a0 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
310b0 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
310c0 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
310d0 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
310e0 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
310f0 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
31100 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
31110 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
31120 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
31130 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
31140 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
31150 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
31160 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
31170 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
31180 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
31190 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
311a0 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
311b0 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
311c0 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
311d0 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
311e0 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
311f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
31200 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
31210 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
31220 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
31230 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
31240 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
31250 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
31260 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
31270 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
31280 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
31290 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
312a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
312b0 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
312c0 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
312d0 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
312e0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
312f0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
31300 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31310 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
31320 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
31330 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
31340 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
31350 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
31360 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
31370 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31380 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
31390 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
313a0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
313b0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
313c0 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
313d0 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
313e0 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
313f0 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
31400 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
31410 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
31420 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31430 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
31440 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
31450 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
31460 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
31470 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31480 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
31490 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
314a0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
314b0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
314c0 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
314d0 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
314e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
314f0 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
31500 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
31510 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
31520 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
31530 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
31540 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
31550 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
31560 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
31570 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
31580 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
31590 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
315a0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
315b0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
315c0 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
315d0 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
315e0 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
315f0 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
31600 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
31610 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
31620 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
31630 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
31640 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
31650 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
31660 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
31670 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
31680 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
31690 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
316a0 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
316b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
316c0 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
316d0 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
316e0 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
316f0 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
31700 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
31710 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
31720 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
31730 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
31740 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
31750 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
31760 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
31770 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
31780 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
31790 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
317a0 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
317b0 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
317c0 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  EM].)^.*/.SQLITE
317d0 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
317e0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
317f0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
31800 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
31810 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31830 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
31840 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
31850 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31860 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31870 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
31880 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
31890 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73  ITE_API double s
318a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
318b0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
318c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
318d0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
318e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
318f0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31900 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
31910 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
31920 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
31930 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
31940 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
31950 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
31960 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
31970 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
31980 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
31990 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
319a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
319b0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
319c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
319d0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
319e0 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
319f0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
31a00 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
31a10 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31a20 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
31a30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
31a40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
31a50 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
31a60 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
31a70 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
31a80 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
31a90 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
31aa0 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
31ab0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
31ac0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
31ad0 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
31ae0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31af0 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
31b00 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
31b10 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
31b20 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
31b30 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
31b40 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
31b50 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
31b60 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
31b70 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
31b80 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
31b90 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
31ba0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
31bb0 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
31bc0 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
31bd0 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
31be0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
31bf0 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
31c00 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
31c10 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
31c20 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
31c30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
31c40 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
31c50 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
31c60 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
31c70 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
31c80 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
31c90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
31ca0 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
31cb0 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
31cc0 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
31cd0 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
31ce0 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
31cf0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
31d00 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
31d10 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
31d20 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
31d30 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
31d40 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
31d50 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
31d60 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
31d70 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
31d80 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
31d90 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
31da0 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
31db0 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
31dc0 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
31dd0 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
31de0 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
31df0 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
31e00 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
31e10 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
31e20 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
31e30 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
31e40 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
31e50 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
31e60 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31e70 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
31e80 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
31e90 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
31ea0 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
31eb0 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
31ec0 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
31ed0 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
31ee0 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
31ef0 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
31f00 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
31f10 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
31f20 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  rruption..*/.SQL
31f30 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31f40 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
31f50 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
31f60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
31f70 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
31f80 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
31f90 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
31fa0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
31fb0 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
31fc0 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
31fd0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31fe0 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
31ff0 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
32000 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
32010 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
32020 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
32030 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
32040 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
32050 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
32060 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
32070 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
32080 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
32090 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
320a0 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
320b0 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
320c0 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
320d0 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
320e0 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
320f0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
32100 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
32110 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
32120 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
32130 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
32140 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
32150 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
32160 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
32170 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
32180 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
32190 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
321a0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
321b0 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
321c0 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
321d0 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
321e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
321f0 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
32200 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
32210 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
32220 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
32230 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
32240 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
32250 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
32260 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
32270 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
32280 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
32290 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
322a0 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
322b0 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
322c0 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
322d0 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
322e0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
322f0 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
32300 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
32310 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
32320 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
32330 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
32340 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
32350 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
32360 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32370 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nt] S..*/.SQLITE
32380 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
32390 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
323a0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
323b0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
323c0 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
323d0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
323e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
323f0 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
32400 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
32410 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
32420 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
32430 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
32440 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
32450 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
32460 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
32470 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
32480 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
32490 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
324a0 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
324b0 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
324c0 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
324d0 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
324e0 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
324f0 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
32500 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
32510 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
32520 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
32530 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
32540 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
32550 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
32560 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
32570 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
32580 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
32590 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
325a0 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
325b0 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
325c0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
325d0 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
325e0 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
325f0 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
32600 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32610 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
32620 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
32630 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
32640 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32650 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
32660 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
32670 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
32680 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
32690 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
326a0 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
326b0 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
326c0 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
326d0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
326e0 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
326f0 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
32700 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
32710 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
32720 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
32730 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
32740 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
32750 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
32760 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
32770 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
32780 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
32790 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
327a0 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
327b0 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
327c0 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
327d0 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
327e0 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
327f0 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
32800 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
32810 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
32820 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
32830 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
32840 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
32850 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
32860 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
32870 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
32880 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
32890 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
328a0 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
328b0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
328c0 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
328d0 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
328e0 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
328f0 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
32900 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
32910 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
32920 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
32930 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
32940 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
32950 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
32960 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
32970 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
32980 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
32990 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
329a0 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
329b0 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
329c0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
329d0 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
329e0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
329f0 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
32a00 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
32a10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
32a20 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
32a30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
32a40 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
32a50 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
32a60 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
32a70 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
32a80 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
32a90 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
32aa0 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
32ab0 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79  rameters.  Every
32ac0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
32ad0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
32ae0 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  t be able to wor
32af0 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c  k.** with UTF-8,
32b00 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
32b10 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
32b20 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32b30 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
32b40 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
32b50 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
32b60 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20  n another.  ^An 
32b70 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a  application may.
32b80 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
32b90 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
32ba0 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
32bb0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
32bc0 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
32bd0 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
32be0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
32bf0 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
32c00 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
32c10 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  p..** ^When mult
32c20 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
32c30 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
32c40 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
32c50 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
32c60 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
32c70 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
32c80 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
32c90 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
32ca0 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
32cb0 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
32cc0 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
32cd0 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
32ce0 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78  ot care what tex
32cf0 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73  t.** encoding is
32d00 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
32d10 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
32d20 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54  should be [SQLIT
32d30 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  E_ANY]..**.** ^(
32d40 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
32d50 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
32d60 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
32d70 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
32d80 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
32d90 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
32da0 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
32db0 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
32dc0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
32dd0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
32de0 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
32df0 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
32e00 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
32e10 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
32e20 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
32e30 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
32e40 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
32e50 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
32e60 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
32e70 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
32e80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
32e90 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
32ea0 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
32eb0 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
32ec0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
32ed0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
32ee0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
32ef0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
32f00 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
32f10 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
32f20 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
32f30 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
32f40 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
32f50 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
32f60 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
32f70 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
32f80 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
32f90 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
32fa0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
32fb0 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
32fc0 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
32fd0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
32fe0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
32ff0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
33000 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
33010 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
33020 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
33030 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
33040 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
33050 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
33060 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
33070 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
33080 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
33090 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
330a0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
330b0 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
330c0 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
330d0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
330e0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
330f0 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
33100 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
33110 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
33120 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
33130 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33140 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
33150 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
33160 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
33170 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
33180 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
33190 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
331a0 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
331b0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
331c0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
331d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
331e0 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
331f0 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
33200 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
33210 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33220 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
33230 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
33240 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
33250 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
33260 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
33270 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
33280 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
33290 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
332a0 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
332b0 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
332c0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
332d0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
332e0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
332f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
33300 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
33310 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
33320 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
33330 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
33340 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
33350 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
33360 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
33370 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
33380 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
33390 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
333a0 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
333b0 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
333c0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
333d0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
333e0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
333f0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
33400 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
33410 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
33420 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
33430 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
33440 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
33450 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
33460 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
33470 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
33480 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
33490 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
334a0 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
334b0 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
334c0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
334d0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
334e0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
334f0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
33500 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
33510 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
33520 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
33530 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
33540 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
33550 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
33560 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
33570 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
33580 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
33590 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
335a0 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
335b0 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
335c0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
335d0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
335e0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
335f0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
33600 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
33610 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
33620 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
33630 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
33640 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
33650 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
33660 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
33670 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
33680 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33690 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
336a0 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
336b0 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
336c0 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
336d0 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
336e0 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
336f0 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
33700 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33710 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33720 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
33730 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
33740 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
33750 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
33760 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
33770 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53  3_context*).);.S
33780 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
33790 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
337a0 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
337b0 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
337c0 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
337d0 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
337e0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
337f0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
33800 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
33810 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33820 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
33830 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
33840 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
33850 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
33860 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
33870 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
33880 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
33890 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
338a0 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
338b0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
338c0 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
338d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
338e0 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
338f0 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
33900 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
33910 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
33920 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
33930 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
33940 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
33950 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
33960 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33970 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33980 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
33990 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
339a0 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
339b0 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
339c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
339d0 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
339e0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
339f0 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
33a00 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
33a10 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
33a20 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
33a30 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
33a40 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
33a50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33a60 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
33a70 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33a80 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
33a90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33aa0 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
33ab0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
33ac0 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
33ad0 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
33ae0 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
33af0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
33b00 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
33b10 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
33b20 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
33b30 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
33b40 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
33b50 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
33b60 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
33b70 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
33b80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
33b90 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
33ba0 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
33bb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
33bc0 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
33bd0 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
33be0 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
33bf0 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
33c00 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
33c10 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
33c20 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
33c30 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
33c40 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
33c50 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
33c60 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
33c70 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
33c80 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
33c90 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
33ca0 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
33cb0 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
33cc0 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
33cd0 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
33ce0 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
33cf0 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
33d00 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
33d10 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
33d20 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
33d30 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
33d40 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
33d50 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
33d60 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
33d70 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
33d80 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
33d90 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
33da0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
33db0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
33dc0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
33dd0 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
33de0 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
33df0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
33e00 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
33e10 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
33e20 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
33e30 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
33e40 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
33e50 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
33e60 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
33e70 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
33e80 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
33e90 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
33ea0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
33eb0 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
33ec0 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
33ed0 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
33ee0 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
33ef0 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
33f00 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
33f10 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
33f20 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
33f30 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
33f40 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
33f50 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
33f60 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
33f70 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
33f80 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
33f90 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
33fa0 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
33fb0 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
33fc0 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
33fd0 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
33fe0 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
33ff0 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
34000 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
34010 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
34020 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
34030 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34040 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
34050 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34060 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
34070 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
34080 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
34090 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
340a0 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
340b0 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
340c0 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
340d0 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
340e0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
340f0 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
34100 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34110 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
34120 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
34130 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
34140 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
34150 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
34160 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
34170 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
34180 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
34190 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
341a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
341b0 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
341c0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
341d0 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
341e0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
341f0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
34200 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
34210 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
34220 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
34230 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
34240 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
34250 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
34260 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
34270 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
34280 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
34290 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
342a0 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
342b0 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
342c0 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
342d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
342e0 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
342f0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
34300 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
34310 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
34320 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
34330 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
34340 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
34350 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
34360 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
34370 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
34380 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
34390 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
343a0 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
343b0 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
343c0 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
343d0 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
343e0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
343f0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
34400 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
34410 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
34420 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
34430 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
34440 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
34450 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
34460 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
34470 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
34480 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
34490 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
344a0 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
344b0 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
344c0 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
344d0 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
344e0 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
344f0 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
34500 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
34510 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
34520 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
34530 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
34540 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
34550 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
34560 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
34570 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
34580 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
34590 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
345a0 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
345b0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
345c0 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
345d0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
345e0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
345f0 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
34600 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
34610 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
34620 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
34630 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
34640 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
34650 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
34660 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
34670 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
34680 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
34690 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
346a0 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
346b0 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
346c0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
346d0 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
346e0 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
346f0 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
34700 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
34710 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
34720 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34730 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
34740 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
34750 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
34760 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
34770 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
34780 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
34790 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
347a0 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
347b0 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
347c0 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
347d0 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
347e0 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
347f0 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
34800 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
34810 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
34820 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34830 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
34840 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
34850 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
34860 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
34870 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
34880 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
34890 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
348a0 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
348b0 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
348c0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
348d0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
348e0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
348f0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
34900 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
34910 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
34920 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
34930 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
34940 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
34950 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
34960 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
34970 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
34980 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
34990 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
349a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
349b0 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
349c0 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
349d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
349e0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
349f0 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
34a00 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
34a10 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
34a20 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
34a30 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34a40 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
34a50 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
34a60 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
34a70 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
34a80 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
34a90 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
34aa0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
34ab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34ac0 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
34ad0 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
34ae0 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
34af0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
34b00 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
34b10 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
34b20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
34b30 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
34b40 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
34b50 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
34b60 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
34b70 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
34b80 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
34b90 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
34ba0 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
34bb0 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
34bc0 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
34bd0 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
34be0 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
34bf0 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
34c00 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
34c10 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
34c20 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
34c30 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
34c40 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
34c50 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
34c60 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
34c70 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
34c80 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
34c90 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
34ca0 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
34cb0 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
34cc0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
34cd0 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
34ce0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
34cf0 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
34d00 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
34d10 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
34d20 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
34d30 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
34d40 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
34d50 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
34d60 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
34d70 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
34d80 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
34d90 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
34da0 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
34db0 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
34dc0 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
34dd0 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
34de0 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
34df0 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
34e00 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
34e10 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
34e20 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
34e30 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
34e40 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
34e50 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
34e60 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
34e70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
34e80 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
34e90 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
34ea0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
34eb0 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65  er if N is.** le
34ec0 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
34ed0 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
34ee0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
34ef0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
34f00 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
34f10 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
34f20 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
34f30 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
34f40 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
34f50 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
34f60 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
34f70 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
34f80 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
34f90 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
34fa0 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
34fb0 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
34fc0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
34fd0 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
34fe0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
34ff0 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
35000 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
35010 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
35020 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  allocation.)^.**
35030 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
35040 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
35050 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
35060 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
35070 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
35080 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
35090 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
350a0 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
350b0 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
350c0 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
350d0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
350e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
350f0 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
35100 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
35110 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
35120 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
35130 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
35140 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
35150 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
35160 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
35170 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
35180 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
35190 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
351a0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
351b0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
351c0 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
351d0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
351e0 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
351f0 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
35200 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
35210 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
35220 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
35230 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35240 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
35250 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
35260 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
35270 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
35280 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
35290 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
352a0 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
352b0 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
352c0 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
352d0 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
352e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
352f0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
35300 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
35310 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
35320 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
35330 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
35340 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
35350 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
35360 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
35370 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
35380 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
35390 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
353a0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
353b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
353c0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
353d0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
353e0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
353f0 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
35400 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
35410 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
35420 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
35430 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
35440 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
35450 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
35460 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
35470 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35480 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
35490 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
354a0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
354b0 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
354c0 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
354d0 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
354e0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
354f0 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
35500 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35510 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
35520 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
35530 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
35540 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
35550 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
35560 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
35570 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
35580 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
35590 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
355a0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
355b0 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
355c0 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
355d0 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
355e0 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
355f0 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
35600 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
35610 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
35620 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
35630 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
35640 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
35650 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
35660 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
35670 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
35680 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
35690 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
356a0 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
356b0 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
356c0 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
356d0 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
356e0 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
356f0 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
35700 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
35710 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
35720 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
35730 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
35740 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
35750 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
35760 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
35770 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
35780 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
35790 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
357a0 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
357b0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
357c0 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
357d0 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
357e0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
357f0 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
35800 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
35810 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
35820 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
35830 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
35840 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
35850 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
35860 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
35870 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
35880 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
35890 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
358a0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
358b0 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
358c0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
358d0 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
358e0 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
358f0 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
35900 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
35910 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
35920 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
35930 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
35940 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35950 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
35960 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
35970 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
35980 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
35990 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
359a0 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
359b0 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
359c0 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
359d0 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
359e0 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
359f0 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
35a00 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
35a10 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
35a20 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
35a30 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
35a40 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
35a50 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
35a60 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
35a70 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
35a80 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
35a90 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
35aa0 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
35ab0 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
35ac0 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
35ad0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
35ae0 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
35af0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
35b00 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
35b10 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
35b20 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
35b30 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
35b40 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
35b50 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
35b60 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
35b70 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
35b80 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
35b90 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
35ba0 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
35bb0 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
35bc0 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
35bd0 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
35be0 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
35bf0 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
35c00 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
35c10 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
35c20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
35c30 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
35c40 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
35c50 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
35c60 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
35c70 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
35c80 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
35c90 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
35ca0 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
35cb0 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
35cc0 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
35cd0 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
35ce0 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
35cf0 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
35d00 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
35d10 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
35d20 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
35d30 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
35d40 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
35d50 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
35d60 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
35d70 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
35d80 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
35d90 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
35da0 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
35db0 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
35dc0 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
35dd0 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
35de0 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
35df0 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
35e00 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
35e10 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
35e20 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
35e30 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
35e40 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
35e50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35e60 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
35e70 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
35e80 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
35e90 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
35ea0 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
35eb0 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
35ec0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35ed0 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
35ee0 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
35ef0 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
35f00 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
35f10 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
35f20 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
35f30 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
35f40 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
35f50 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
35f60 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
35f70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
35f80 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
35f90 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
35fa0 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
35fb0 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
35fc0 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
35fd0 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
35fe0 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
35ff0 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
36000 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
36010 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
36020 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
36030 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
36040 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
36050 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
36060 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
36070 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
36080 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
36090 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
360a0 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
360b0 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
360c0 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
360d0 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
360e0 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
360f0 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
36100 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
36110 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
36120 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
36130 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
36140 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
36150 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
36160 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
36170 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
36180 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
36190 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
361a0 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
361b0 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
361c0 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
361d0 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
361e0 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
361f0 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
36200 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
36210 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
36220 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
36230 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
36240 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
36250 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
36260 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
36270 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
36280 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
36290 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
362a0 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
362b0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
362c0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
362d0 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
362e0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
362f0 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
36300 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
36310 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
36320 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
36330 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
36340 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
36350 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
36360 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
36370 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
36380 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
36390 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
363a0 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
363b0 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
363c0 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
363d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
363e0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
363f0 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
36400 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
36410 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
36420 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
36430 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
36440 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
36450 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
36460 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
36470 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
36480 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
36490 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
364a0 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
364b0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
364c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
364d0 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
364e0 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
364f0 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
36500 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36510 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
36520 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
36530 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
36540 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
36550 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
36560 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
36570 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
36580 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
36590 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
365a0 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
365b0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
365c0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
365d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
365e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
365f0 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
36600 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
36610 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
36620 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
36630 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36640 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
36650 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36660 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
36670 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
36680 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
36690 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
366a0 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
366b0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
366c0 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
366d0 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
366e0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
366f0 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
36700 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
36710 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36720 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
36730 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
36740 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
36750 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
36760 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
36770 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
36780 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36790 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
367a0 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
367b0 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
367c0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
367d0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
367e0 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
367f0 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
36800 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
36810 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
36820 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36830 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
36840 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36850 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
36860 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
36870 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
36880 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
36890 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
368a0 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
368b0 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
368c0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
368d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
368e0 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
368f0 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
36900 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
36910 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
36920 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
36930 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
36940 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
36950 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
36960 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
36970 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
36980 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36990 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
369a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
369b0 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
369c0 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
369d0 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
369e0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
369f0 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
36a00 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
36a10 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
36a20 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
36a30 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
36a40 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
36a50 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
36a60 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
36a70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36a80 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
36a90 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
36aa0 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
36ab0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
36ac0 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
36ad0 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
36ae0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
36af0 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
36b00 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
36b10 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
36b20 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
36b30 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
36b40 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
36b50 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
36b60 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
36b70 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
36b80 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
36b90 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
36ba0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36bb0 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  or_toobig() inte
36bc0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
36bd0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
36be0 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
36bf0 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
36c00 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
36c10 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
36c20 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
36c30 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
36c40 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ror_nomem() inte
36c50 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
36c60 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
36c70 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
36c80 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
36c90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
36ca0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
36cb0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
36cc0 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
36cd0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
36ce0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
36cf0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36d00 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36d10 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
36d20 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
36d30 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
36d40 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
36d50 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36d60 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
36d70 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
36d80 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
36d90 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
36da0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
36db0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
36dc0 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
36dd0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
36de0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
36df0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
36e00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
36e10 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
36e20 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
36e30 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
36e40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36e50 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
36e60 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
36e70 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
36e80 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
36e90 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
36ea0 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
36eb0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
36ec0 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
36ed0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
36ee0 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
36ef0 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
36f00 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
36f10 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36f20 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36f30 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
36f40 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
36f50 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
36f60 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
36f70 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
36f80 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
36f90 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
36fa0 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
36fb0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
36fc0 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
36fd0 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
36fe0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
36ff0 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
37000 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
37010 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37020 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
37030 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
37040 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
37050 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37060 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
37070 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
37080 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
37090 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
370a0 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
370b0 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
370c0 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
370d0 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
370e0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
370f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
37100 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
37110 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
37120 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
37130 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
37140 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
37150 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
37160 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
37170 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
37180 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
37190 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
371a0 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
371b0 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74  on result.  If t
371c0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
371d0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
371e0 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73  , then it.** mus
371f0 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
37200 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74  fset into the st
37210 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e  ring where the N
37220 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
37230 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66  uld.** appear if
37240 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
37250 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64  e NUL terminated
37260 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
37270 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a  aracters occur.*
37280 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  * in the string 
37290 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74  at a byte offset
372a0 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68   that is less th
372b0 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  an the value of 
372c0 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d  the 3rd.** param
372d0 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  eter, then the r
372e0 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
372f0 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62  will contain emb
37300 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74  edded NULs and t
37310 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20  he.** result of 
37320 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72  expressions oper
37330 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73  ating on strings
37340 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
37350 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
37360 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
37370 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37380 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37390 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
373a0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
373b0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
373c0 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
373d0 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
373e0 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
373f0 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
37400 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
37410 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
37420 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
37430 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
37440 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
37450 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
37460 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
37470 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37480 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
37490 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
374a0 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
374b0 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
374c0 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
374d0 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
374e0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
374f0 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
37500 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
37510 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
37520 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
37530 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
37540 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
37550 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
37560 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
37570 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
37580 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
37590 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
375a0 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
375b0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
375c0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
375d0 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
375e0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
375f0 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
37600 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
37610 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
37620 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
37630 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
37640 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
37650 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
37660 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
37670 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
37680 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
37690 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
376a0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
376b0 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
376c0 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
376d0 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
376e0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
376f0 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
37700 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
37710 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
37720 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
37730 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
37740 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
37750 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
37760 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
37770 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
37780 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
37790 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
377a0 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
377b0 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
377c0 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
377d0 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
377e0 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
377f0 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
37800 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
37810 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
37820 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
37830 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
37840 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
37850 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
37860 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
37870 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
37880 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
37890 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
378a0 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
378b0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
378c0 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
378d0 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
378e0 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
378f0 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
37900 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
37910 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
37920 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
37930 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
37940 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
37950 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37960 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
37970 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
37980 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
37990 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
379a0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
379b0 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
379c0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
379d0 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
379e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
379f0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
37a00 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
37a10 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37a20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
37a30 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
37a40 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
37a50 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37a60 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37a70 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
37a80 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
37a90 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  ar*, int);.SQLIT
37aa0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
37ab0 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
37ac0 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
37ad0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
37ae0 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
37af0 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37b00 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
37b10 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
37b20 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
37b30 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
37b40 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
37b50 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
37b60 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
37b70 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
37b80 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
37b90 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37ba0 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
37bb0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
37bc0 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
37bd0 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
37be0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
37bf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37c00 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
37c10 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
37c20 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41  int64);.SQLITE_A
37c30 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
37c40 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
37c50 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
37c60 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
37c70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37c80 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
37c90 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
37ca0 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
37cb0 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
37cc0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
37cd0 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
37ce0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
37cf0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
37d00 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
37d10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
37d20 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37d30 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
37d40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
37d50 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
37d60 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
37d70 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
37d80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
37d90 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
37da0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
37db0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
37dc0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
37dd0 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
37de0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
37df0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
37e00 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
37e10 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
37e20 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
37e30 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
37e40 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
37e50 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
37e60 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
37e70 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
37e80 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
37e90 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
37ea0 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
37eb0 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
37ec0 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
37ed0 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
37ee0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
37ef0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
37f00 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
37f10 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
37f20 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
37f30 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
37f40 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
37f50 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
37f60 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
37f70 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
37f80 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
37f90 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
37fa0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
37fb0 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
37fc0 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
37fd0 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
37fe0 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
37ff0 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
38000 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
38010 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
38020 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
38030 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
38040 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
38050 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
38060 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
38070 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
38080 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
38090 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
380a0 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
380b0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
380c0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
380d0 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
380e0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
380f0 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
38100 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
38110 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
38120 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
38130 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
38140 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
38150 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
38160 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
38170 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
38180 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
38190 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
381a0 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
381b0 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
381c0 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
381d0 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
381e0 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
381f0 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
38200 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
38210 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
38220 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
38230 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
38240 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
38250 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
38260 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
38270 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
38280 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
38290 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
382a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
382b0 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
382c0 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
382d0 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
382e0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
382f0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
38300 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
38310 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
38320 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
38330 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
38340 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
38350 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
38360 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
38370 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
38380 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
38390 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
383a0 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
383b0 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
383c0 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
383d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
383e0 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
383f0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
38400 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
38410 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
38420 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
38430 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
38440 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
38450 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
38460 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
38470 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
38480 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
38490 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
384a0 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
384b0 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
384c0 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
384d0 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
384e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
384f0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
38500 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
38510 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
38520 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
38530 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
38540 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
38550 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
38560 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
38570 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
38580 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
38590 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
385a0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
385b0 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
385c0 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
385d0 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
385e0 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
385f0 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
38600 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
38610 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
38620 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
38630 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ond,.** respecti
38640 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69  vely.  A collati
38650 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
38660 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
38670 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a  he same answer.*
38680 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65  * given the same
38690 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f   inputs.  If two
386a0 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69   or more collati
386b0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
386c0 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74   registered.** t
386d0 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61  o the same colla
386e0 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67  tion name (using
386f0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
38700 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e  Rep values) then
38710 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76   all.** must giv
38720 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20  e an equivalent 
38730 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f  answer when invo
38740 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c  ked with equival
38750 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  ent strings..** 
38760 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
38770 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79  nction must obey
38780 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
38790 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c  roperties for al
387a0 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20  l.** strings A, 
387b0 42 2c