System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact af36ef5105449c9dcc12456391164f7ac0fb13f3:


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 35 2e 20 20  ersion 3.7.15.  
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 35 22 0a         "3.7.15".
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 35 0a 23 64 65 66 69 6e 65 20 53 51  07015.#define SQ
5d90: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 20  LITE_SOURCE_ID  
5da0: 20 20 20 20 22 32 30 31 32 2d 30 39 2d 31 39 20      "2012-09-19 
5db0: 32 31 3a 31 35 3a 34 36 20 39 34 62 34 38 30 36  21:15:46 94b4806
5dc0: 34 64 62 33 63 62 62 34 33 65 39 31 31 66 64 66  4db3cbb43e911fdf
5dd0: 37 31 38 33 32 31 38 62 30 38 31 34 36 65 63 31  7183218b08146ec1
5de0: 30 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  0"../*.** 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 41 4e  efine SQLITE_CAN
a3f0: 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48 20 20  TOPEN_FULLPATH  
a400: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
a410: 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29 29 0a  TOPEN | (3<<8)).
a420: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
a430: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
a440: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
a450: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (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 52 45 43 4f 56 45 52  READONLY_RECOVER
a480: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
a490: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
a4a0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a4b0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
a4c0: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
a4d0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
a4e0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
a4f0: 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c 4c 42 41  ITE_ABORT_ROLLBA
a500: 43 4b 20 20 20 20 20 20 20 20 20 20 28 53 51 4c  CK          (SQL
a510: 49 54 45 5f 41 42 4f 52 54 20 7c 20 28 32 3c 3c  ITE_ABORT | (2<<
a520: 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  8))../*.** CAPI3
a530: 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20 46  REF: Flags For F
a540: 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74 69  ile Open Operati
a550: 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
a560: 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20 69  bit values are i
a570: 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20  ntended for use 
a580: 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70 61  in the.** 3rd pa
a590: 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 5b  rameter to the [
a5a0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
a5b0: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e 64  )] interface and
a5c0: 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20 70  .** in the 4th p
a5d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
a5e0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
a5f0: 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 23  en] method..*/.#
a600: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a610: 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20 20  EN_READONLY     
a620: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20 20      0x00000001  
a630: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
a640: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
a650: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a660: 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20 20  EN_READWRITE    
a670: 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20 20      0x00000002  
a680: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
a690: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
a6a0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a6b0: 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20 20  EN_CREATE       
a6c0: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20 20      0x00000004  
a6d0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
a6e0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
a6f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a700: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
a710: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20 20      0x00000008  
a720: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a730: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a740: 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20  EN_EXCLUSIVE    
a750: 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20 20      0x00000010  
a760: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a770: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a780: 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20 20  EN_AUTOPROXY    
a790: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20 20      0x00000020  
a7a0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a7b0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a7c0: 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  EN_URI          
a7d0: 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20 20      0x00000040  
a7e0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
a7f0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
a800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a810: 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20 20  EN_MEMORY       
a820: 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20 20      0x00000080  
a830: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
a840: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
a850: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a860: 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20 20  EN_MAIN_DB      
a870: 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20 20      0x00000100  
a880: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a890: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a8a0: 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20 20  EN_TEMP_DB      
a8b0: 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20 20      0x00000200  
a8c0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a8d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a8e0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 20  EN_TRANSIENT_DB 
a8f0: 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20 20      0x00000400  
a900: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a920: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 20  EN_MAIN_JOURNAL 
a930: 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20 20      0x00000800  
a940: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a960: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 20  EN_TEMP_JOURNAL 
a970: 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20 20      0x00001000  
a980: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a990: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a9a0: 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20 20  EN_SUBJOURNAL   
a9b0: 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20 20      0x00002000  
a9c0: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
a9d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
a9e0: 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41  EN_MASTER_JOURNA
a9f0: 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20 20  L   0x00004000  
aa00: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 23  /* VFS only */.#
aa10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
aa20: 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20 20  EN_NOMUTEX      
aa30: 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20 20      0x00008000  
aa40: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
aa50: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
aa60: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
aa70: 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20 20  EN_FULLMUTEX    
aa80: 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20 20      0x00010000  
aa90: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
aaa0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
aab0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
aac0: 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  EN_SHAREDCACHE  
aad0: 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20 20      0x00020000  
aae0: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
aaf0: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
ab00: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
ab10: 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 20  EN_PRIVATECACHE 
ab20: 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20 20      0x00040000  
ab30: 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74 65  /* Ok for sqlite
ab40: 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a 23  3_open_v2() */.#
ab50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 50  define SQLITE_OP
ab60: 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20 20  EN_WAL          
ab70: 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20 20      0x00080000  
ab80: 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a 0a  /* VFS only */..
ab90: 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20 20  /* Reserved:    
aba0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
abb0: 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30 20       0x00F00000 
abc0: 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
abd0: 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72 61  EF: Device Chara
abe0: 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  cteristics.**.**
abf0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
ac00: 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68  acteristics meth
ac10: 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  od of the [sqlit
ac20: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
ac30: 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 73  * object returns
ac40: 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
ac50: 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f 66  h is a vector of
ac60: 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76 61   these.** bit va
ac70: 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67 20  lues expressing 
ac80: 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73 74  I/O characterist
ac90: 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73 20  ics of the mass 
aca0: 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69 63  storage.** devic
acb0: 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68 65  e that holds the
acc0: 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20 5b   file that the [
acd0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
ace0: 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74 6f  ds].** refers to
acf0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49  ..**.** The SQLI
ad00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20  TE_IOCAP_ATOMIC 
ad10: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
ad20: 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f  hat all writes o
ad30: 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72  f.** any size ar
ad40: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
ad50: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
ad60: 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20  ICnnn values.** 
ad70: 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73  mean that writes
ad80: 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20   of blocks that 
ad90: 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e  are nnn bytes in
ada0: 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65   size and.** are
adb0: 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61   aligned to an a
adc0: 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20  ddress which is 
add0: 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69  an integer multi
ade0: 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72  ple of.** nnn ar
adf0: 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53  e atomic.  The S
ae00: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
ae10: 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65  _APPEND value me
ae20: 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e  ans.** that when
ae30: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
ae40: 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65  d to a file, the
ae50: 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65   data is appende
ae60: 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20  d.** first then 
ae70: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
ae80: 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64  file is extended
ae90: 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65  , never the othe
aea0: 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e  r.** way around.
aeb0: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
aec0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72  AP_SEQUENTIAL pr
aed0: 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61  operty means tha
aee0: 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  t.** information
aef0: 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64   is written to d
af00: 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20  isk in the same 
af10: 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a  order as calls.*
af20: 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20 20  * to xWrite().  
af30: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
af40: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
af50: 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d 65  RITE property me
af60: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74 65  ans that.** afte
af70: 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77 69  r reboot followi
af80: 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70 6f  ng a crash or po
af90: 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f 6e  wer loss, the on
afa0: 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a 2a  ly bytes in a.**
afb0: 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65 20   file that were 
afc0: 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20 61  written at the a
afd0: 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65 6c  pplication level
afe0: 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61 6e   might have chan
aff0: 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ged.** and that 
b000: 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c 20  adjacent bytes, 
b010: 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68 69  even bytes withi
b020: 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74 6f  n the same secto
b030: 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e 74  r are.** guarant
b040: 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61 6e  eed to be unchan
b050: 67 65 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ged..*/.#define 
b060: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
b070: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
b080: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
b090: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
b0a0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
b0b0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
b0c0: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
b0d0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
b0e0: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
b0f0: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
b100: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
b110: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
b120: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
b130: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
b140: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
b150: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
b160: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
b170: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
b180: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
b190: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
b1a0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b1b0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
b1c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
b1d0: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
b1e0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
b1f0: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
b200: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
b210: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
b220: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
b230: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
b240: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
b250: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
b260: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
b270: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
b280: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
b290: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
b2a0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
b2b0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
b2c0: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
b2d0: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
b2e0: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
b2f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
b300: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
b310: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
b320: 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  00../*.** CAPI3R
b330: 45 46 3a 20 46 69 6c 65 20 4c 6f 63 6b 69 6e 67  EF: File Locking
b340: 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a 2a 20 53 51   Levels.**.** SQ
b350: 4c 69 74 65 20 75 73 65 73 20 6f 6e 65 20 6f 66  Lite uses one of
b360: 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20 76   these integer v
b370: 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65 63  alues as the sec
b380: 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ond.** argument 
b390: 74 6f 20 63 61 6c 6c 73 20 69 74 20 6d 61 6b 65  to calls it make
b3a0: 73 20 74 6f 20 74 68 65 20 78 4c 6f 63 6b 28 29  s to the xLock()
b3b0: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d   and xUnlock() m
b3c0: 65 74 68 6f 64 73 0a 2a 2a 20 6f 66 20 61 6e 20  ethods.** of an 
b3d0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
b3e0: 6f 64 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a  ods] object..*/.
b3f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
b400: 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20 20 20 20 20  OCK_NONE        
b410: 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    0.#define SQLI
b420: 54 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 20 20  TE_LOCK_SHARED  
b430: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
b440: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45  SQLITE_LOCK_RESE
b450: 52 56 45 44 20 20 20 20 20 20 32 0a 23 64 65 66  RVED      2.#def
b460: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
b470: 50 45 4e 44 49 4e 47 20 20 20 20 20 20 20 33 0a  PENDING       3.
b480: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
b490: 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 20 20 20  OCK_EXCLUSIVE   
b4a0: 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33    4../*.** CAPI3
b4b0: 52 45 46 3a 20 53 79 6e 63 68 72 6f 6e 69 7a 61  REF: Synchroniza
b4c0: 74 69 6f 6e 20 54 79 70 65 20 46 6c 61 67 73 0a  tion Type Flags.
b4d0: 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53 51 4c 69 74  **.** When SQLit
b4e0: 65 20 69 6e 76 6f 6b 65 73 20 74 68 65 20 78 53  e invokes the xS
b4f0: 79 6e 63 28 29 20 6d 65 74 68 6f 64 20 6f 66 20  ync() method of 
b500: 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  an.** [sqlite3_i
b510: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63  o_methods] objec
b520: 74 20 69 74 20 75 73 65 73 20 61 20 63 6f 6d 62  t it uses a comb
b530: 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a 2a 20 74 68  ination of.** th
b540: 65 73 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ese integer valu
b550: 65 73 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  es as the second
b560: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
b570: 20 57 68 65 6e 20 74 68 65 20 53 51 4c 49 54 45   When the SQLITE
b580: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 66  _SYNC_DATAONLY f
b590: 6c 61 67 20 69 73 20 75 73 65 64 2c 20 69 74 20  lag is used, it 
b5a0: 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 0a 2a  means that the.*
b5b0: 2a 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e  * sync operation
b5c0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 66   only needs to f
b5d0: 6c 75 73 68 20 64 61 74 61 20 74 6f 20 6d 61 73  lush data to mas
b5e0: 73 20 73 74 6f 72 61 67 65 2e 20 20 49 6e 6f 64  s storage.  Inod
b5f0: 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  e.** information
b600: 20 6e 65 65 64 20 6e 6f 74 20 62 65 20 66 6c 75   need not be flu
b610: 73 68 65 64 2e 20 49 66 20 74 68 65 20 6c 6f 77  shed. If the low
b620: 65 72 20 66 6f 75 72 20 62 69 74 73 20 6f 66 20  er four bits of 
b630: 74 68 65 20 66 6c 61 67 0a 2a 2a 20 65 71 75 61  the flag.** equa
b640: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  l SQLITE_SYNC_NO
b650: 52 4d 41 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73  RMAL, that means
b660: 20 74 6f 20 75 73 65 20 6e 6f 72 6d 61 6c 20 66   to use normal f
b670: 73 79 6e 63 28 29 20 73 65 6d 61 6e 74 69 63 73  sync() semantics
b680: 2e 0a 2a 2a 20 49 66 20 74 68 65 20 6c 6f 77 65  ..** If the lowe
b690: 72 20 66 6f 75 72 20 62 69 74 73 20 65 71 75 61  r four bits equa
b6a0: 6c 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55  l SQLITE_SYNC_FU
b6b0: 4c 4c 2c 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a  LL, that means.*
b6c0: 2a 20 74 6f 20 75 73 65 20 4d 61 63 20 4f 53 20  * to use Mac OS 
b6d0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
b6e0: 20 69 6e 73 74 65 61 64 20 6f 66 20 66 73 79 6e   instead of fsyn
b6f0: 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f  c()..**.** Do no
b700: 74 20 63 6f 6e 66 75 73 65 20 74 68 65 20 53 51  t confuse the SQ
b710: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
b720: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
b730: 5f 46 55 4c 4c 20 66 6c 61 67 73 0a 2a 2a 20 77  _FULL flags.** w
b740: 69 74 68 20 74 68 65 20 5b 50 52 41 47 4d 41 20  ith the [PRAGMA 
b750: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 4e 4f 52  synchronous]=NOR
b760: 4d 41 4c 20 61 6e 64 20 5b 50 52 41 47 4d 41 20  MAL and [PRAGMA 
b770: 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 3d 46 55 4c  synchronous]=FUL
b780: 4c 0a 2a 2a 20 73 65 74 74 69 6e 67 73 2e 20 20  L.** settings.  
b790: 54 68 65 20 5b 73 79 6e 63 68 72 6f 6e 6f 75 73  The [synchronous
b7a0: 20 70 72 61 67 6d 61 5d 20 64 65 74 65 72 6d 69   pragma] determi
b7b0: 6e 65 73 20 77 68 65 6e 20 63 61 6c 6c 73 20 74  nes when calls t
b7c0: 6f 20 74 68 65 0a 2a 2a 20 78 53 79 6e 63 20 56  o the.** xSync V
b7d0: 46 53 20 6d 65 74 68 6f 64 20 6f 63 63 75 72 20  FS method occur 
b7e0: 61 6e 64 20 61 70 70 6c 69 65 73 20 75 6e 69 66  and applies unif
b7f0: 6f 72 6d 6c 79 20 61 63 72 6f 73 73 20 61 6c 6c  ormly across all
b800: 20 70 6c 61 74 66 6f 72 6d 73 2e 0a 2a 2a 20 54   platforms..** T
b810: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  he SQLITE_SYNC_N
b820: 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45  ORMAL and SQLITE
b830: 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73  _SYNC_FULL flags
b840: 20 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 0a 2a   determine how.*
b850: 2a 20 65 6e 65 72 67 65 74 69 63 20 6f 72 20 72  * energetic or r
b860: 69 67 6f 72 6f 75 73 20 6f 72 20 66 6f 72 63 65  igorous or force
b870: 66 75 6c 20 74 68 65 20 73 79 6e 63 20 6f 70 65  ful the sync ope
b880: 72 61 74 69 6f 6e 73 20 61 72 65 20 61 6e 64 0a  rations are and.
b890: 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65 20 61 20 64  ** only make a d
b8a0: 69 66 66 65 72 65 6e 63 65 20 6f 6e 20 4d 61 63  ifference on Mac
b8b0: 20 4f 53 58 20 66 6f 72 20 74 68 65 20 64 65 66   OSX for the def
b8c0: 61 75 6c 74 20 53 51 4c 69 74 65 20 63 6f 64 65  ault SQLite code
b8d0: 2e 0a 2a 2a 20 28 54 68 69 72 64 2d 70 61 72 74  ..** (Third-part
b8e0: 79 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  y VFS implementa
b8f0: 74 69 6f 6e 73 20 6d 69 67 68 74 20 61 6c 73 6f  tions might also
b900: 20 6d 61 6b 65 20 74 68 65 20 64 69 73 74 69 6e   make the distin
b910: 63 74 69 6f 6e 0a 2a 2a 20 62 65 74 77 65 65 6e  ction.** between
b920: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52   SQLITE_SYNC_NOR
b930: 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f 53  MAL and SQLITE_S
b940: 59 4e 43 5f 46 55 4c 4c 2c 20 62 75 74 20 61 6d  YNC_FULL, but am
b950: 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f 70 65 72 61  ong the.** opera
b960: 74 69 6e 67 20 73 79 73 74 65 6d 73 20 6e 61 74  ting systems nat
b970: 69 76 65 6c 79 20 73 75 70 70 6f 72 74 65 64 20  ively supported 
b980: 62 79 20 53 51 4c 69 74 65 2c 20 6f 6e 6c 79 20  by SQLite, only 
b990: 4d 61 63 20 4f 53 58 0a 2a 2a 20 63 61 72 65 73  Mac OSX.** cares
b9a0: 20 61 62 6f 75 74 20 74 68 65 20 64 69 66 66 65   about the diffe
b9b0: 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23 64 65 66 69  rence.).*/.#defi
b9c0: 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e  ne SQLITE_SYNC_N
b9d0: 4f 52 4d 41 4c 20 20 20 20 20 20 20 20 30 78 30  ORMAL        0x0
b9e0: 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c  0002.#define SQL
b9f0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 20 20  ITE_SYNC_FULL   
ba00: 20 20 20 20 20 20 20 30 78 30 30 30 30 33 0a 23         0x00003.#
ba10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
ba20: 4e 43 5f 44 41 54 41 4f 4e 4c 59 20 20 20 20 20  NC_DATAONLY     
ba30: 20 30 78 30 30 30 31 30 0a 0a 2f 2a 0a 2a 2a 20   0x00010../*.** 
ba40: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
ba50: 65 72 66 61 63 65 20 4f 70 65 6e 20 46 69 6c 65  erface Open File
ba60: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e   Handle.**.** An
ba70: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
ba80: 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e 74  object represent
ba90: 73 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 69  s an open file i
baa0: 6e 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74  n the .** [sqlit
bab0: 65 33 5f 76 66 73 20 7c 20 4f 53 20 69 6e 74 65  e3_vfs | OS inte
bac0: 72 66 61 63 65 20 6c 61 79 65 72 5d 2e 20 20 49  rface layer].  I
bad0: 6e 64 69 76 69 64 75 61 6c 20 4f 53 20 69 6e 74  ndividual OS int
bae0: 65 72 66 61 63 65 0a 2a 2a 20 69 6d 70 6c 65 6d  erface.** implem
baf0: 65 6e 74 61 74 69 6f 6e 73 20 77 69 6c 6c 0a 2a  entations will.*
bb00: 2a 20 77 61 6e 74 20 74 6f 20 73 75 62 63 6c 61  * want to subcla
bb10: 73 73 20 74 68 69 73 20 6f 62 6a 65 63 74 20 62  ss this object b
bb20: 79 20 61 70 70 65 6e 64 69 6e 67 20 61 64 64 69  y appending addi
bb30: 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 0a 2a 2a  tional fields.**
bb40: 20 66 6f 72 20 74 68 65 69 72 20 6f 77 6e 20 75   for their own u
bb50: 73 65 2e 20 20 54 68 65 20 70 4d 65 74 68 6f 64  se.  The pMethod
bb60: 73 20 65 6e 74 72 79 20 69 73 20 61 20 70 6f 69  s entry is a poi
bb70: 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73  nter to an.** [s
bb80: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
bb90: 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
bba0: 65 66 69 6e 65 73 20 6d 65 74 68 6f 64 73 20 66  efines methods f
bbb0: 6f 72 20 70 65 72 66 6f 72 6d 69 6e 67 0a 2a 2a  or performing.**
bbc0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
bbd0: 6f 6e 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65  on the open file
bbe0: 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
bbf0: 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69 6c 65  uct sqlite3_file
bc00: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 3b 0a 73   sqlite3_file;.s
bc10: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 66 69  truct sqlite3_fi
bc20: 6c 65 20 7b 0a 20 20 63 6f 6e 73 74 20 73 74 72  le {.  const str
bc30: 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  uct sqlite3_io_m
bc40: 65 74 68 6f 64 73 20 2a 70 4d 65 74 68 6f 64 73  ethods *pMethods
bc50: 3b 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 66 6f  ;  /* Methods fo
bc60: 72 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20 2a  r an open file *
bc70: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
bc80: 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61  3REF: OS Interfa
bc90: 63 65 20 46 69 6c 65 20 56 69 72 74 75 61 6c 20  ce File Virtual 
bca0: 4d 65 74 68 6f 64 73 20 4f 62 6a 65 63 74 0a 2a  Methods Object.*
bcb0: 2a 0a 2a 2a 20 45 76 65 72 79 20 66 69 6c 65 20  *.** Every file 
bcc0: 6f 70 65 6e 65 64 20 62 79 20 74 68 65 20 5b 73  opened by the [s
bcd0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
bce0: 5d 20 6d 65 74 68 6f 64 20 70 6f 70 75 6c 61 74  ] method populat
bcf0: 65 73 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  es an.** [sqlite
bd00: 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 28  3_file] object (
bd10: 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d 6d 6f 6e 6c  or, more commonl
bd20: 79 2c 20 61 20 73 75 62 63 6c 61 73 73 20 6f 66  y, a subclass of
bd30: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
bd40: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 29 20 77  _file] object) w
bd50: 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  ith a pointer to
bd60: 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
bd70: 74 68 69 73 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20  this object..** 
bd80: 54 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69  This object defi
bd90: 6e 65 73 20 74 68 65 20 6d 65 74 68 6f 64 73 20  nes the methods 
bda0: 75 73 65 64 20 74 6f 20 70 65 72 66 6f 72 6d 20  used to perform 
bdb0: 76 61 72 69 6f 75 73 20 6f 70 65 72 61 74 69 6f  various operatio
bdc0: 6e 73 0a 2a 2a 20 61 67 61 69 6e 73 74 20 74 68  ns.** against th
bdd0: 65 20 6f 70 65 6e 20 66 69 6c 65 20 72 65 70 72  e open file repr
bde0: 65 73 65 6e 74 65 64 20 62 79 20 74 68 65 20 5b  esented by the [
bdf0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
be00: 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  ject..**.** If t
be10: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
be20: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 73 65  xOpen] method se
be30: 74 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  ts the sqlite3_f
be40: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
be50: 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20 61 20 6e 6f  ment .** to a no
be60: 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  n-NULL pointer, 
be70: 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
be80: 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e 78 43 6c 6f  _io_methods.xClo
be90: 73 65 20 6d 65 74 68 6f 64 0a 2a 2a 20 6d 61 79  se method.** may
bea0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 65 76 65 6e   be invoked even
beb0: 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   if the [sqlite3
bec0: 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 72 65 70 6f  _vfs.xOpen] repo
bed0: 72 74 65 64 20 74 68 61 74 20 69 74 20 66 61 69  rted that it fai
bee0: 6c 65 64 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c  led.  The.** onl
bef0: 79 20 77 61 79 20 74 6f 20 70 72 65 76 65 6e 74  y way to prevent
bf00: 20 61 20 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73   a call to xClos
bf10: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61  e following a fa
bf20: 69 6c 65 64 20 5b 73 71 6c 69 74 65 33 5f 76 66  iled [sqlite3_vf
bf30: 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20 69 73 20 66  s.xOpen].** is f
bf40: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
bf50: 76 66 73 2e 78 4f 70 65 6e 5d 20 74 6f 20 73 65  vfs.xOpen] to se
bf60: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
bf70: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65 6d  le.pMethods elem
bf80: 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 0a  ent.** to NULL..
bf90: 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20  **.** The flags 
bfa0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e  argument to xSyn
bfb0: 63 20 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20  c may be one of 
bfc0: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52  [SQLITE_SYNC_NOR
bfd0: 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49  MAL] or.** [SQLI
bfe0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20  TE_SYNC_FULL].  
bff0: 54 68 65 20 66 69 72 73 74 20 63 68 6f 69 63 65  The first choice
c000: 20 69 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66   is the normal f
c010: 73 79 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73  sync()..** The s
c020: 65 63 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20  econd choice is 
c030: 61 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  a Mac OS X style
c040: 20 66 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20   fullsync.  The 
c050: 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54  [SQLITE_SYNC_DAT
c060: 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d  AONLY].** flag m
c070: 61 79 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f  ay be ORed in to
c080: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f   indicate that o
c090: 6e 6c 79 20 74 68 65 20 64 61 74 61 20 6f 66 20  nly the data of 
c0a0: 74 68 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20  the file.** and 
c0b0: 6e 6f 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65  not its inode ne
c0c0: 65 64 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64  eds to be synced
c0d0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65  ..**.** The inte
c0e0: 67 65 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c  ger values to xL
c0f0: 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63  ock() and xUnloc
c100: 6b 28 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a  k() are one of.*
c110: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
c120: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45  SQLITE_LOCK_NONE
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 53 48 41 52 45 44 5d 2c  TE_LOCK_SHARED],
c150: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c160: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
c170: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c180: 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20  _LOCK_PENDING], 
c190: 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  or.** <li> [SQLI
c1a0: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
c1b0: 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20  E]..** </ul>.** 
c1c0: 78 4c 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65  xLock() increase
c1d0: 73 20 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c  s the lock. xUnl
c1e0: 6f 63 6b 28 29 20 64 65 63 72 65 61 73 65 73 20  ock() decreases 
c1f0: 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65  the lock..** The
c200: 20 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c   xCheckReservedL
c210: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65  ock() method che
c220: 63 6b 73 20 77 68 65 74 68 65 72 20 61 6e 79 20  cks whether any 
c230: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
c240: 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69  ion,.** either i
c250: 6e 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f  n this process o
c260: 72 20 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20  r in some other 
c270: 70 72 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64  process, is hold
c280: 69 6e 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a  ing a RESERVED,.
c290: 2a 2a 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45  ** PENDING, or E
c2a0: 58 43 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e  XCLUSIVE lock on
c2b0: 20 74 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72   the file.  It r
c2c0: 65 74 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69  eturns true.** i
c2d0: 66 20 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78  f such a lock ex
c2e0: 69 73 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f  ists and false o
c2f0: 74 68 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20  therwise..**.** 
c300: 54 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  The xFileControl
c310: 28 29 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67  () method is a g
c320: 65 6e 65 72 69 63 20 69 6e 74 65 72 66 61 63 65  eneric interface
c330: 20 74 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73   that allows cus
c340: 74 6f 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65  tom.** VFS imple
c350: 6d 65 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69  mentations to di
c360: 72 65 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61  rectly control a
c370: 6e 20 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e  n open file usin
c380: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
c390: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
c3a0: 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  ] interface.  Th
c3b0: 65 20 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72  e second "op" ar
c3c0: 67 75 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20  gument is an.** 
c3d0: 69 6e 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20  integer opcode. 
c3e0: 20 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   The third argum
c3f0: 65 6e 74 20 69 73 20 61 20 67 65 6e 65 72 69 63  ent is a generic
c400: 20 70 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65   pointer intende
c410: 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f  d to.** point to
c420: 20 61 20 73 74 72 75 63 74 75 72 65 20 74 68 61   a structure tha
c430: 74 20 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72  t may contain ar
c440: 67 75 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65  guments or space
c450: 20 69 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20   in which to.** 
c460: 77 72 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c  write return val
c470: 75 65 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20  ues.  Potential 
c480: 75 73 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f  uses for xFileCo
c490: 6e 74 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65  ntrol() might be
c4a0: 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f  .** functions to
c4b0: 20 65 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67   enable blocking
c4c0: 20 6c 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65   locks with time
c4d0: 6f 75 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20  outs, to change 
c4e0: 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73  the.** locking s
c4f0: 74 72 61 74 65 67 79 20 28 66 6f 72 20 65 78 61  trategy (for exa
c500: 6d 70 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d  mple to use dot-
c510: 66 69 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20  file locks), to 
c520: 69 6e 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74  inquire.** about
c530: 20 74 68 65 20 73 74 61 74 75 73 20 6f 66 20 61   the status of a
c540: 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65   lock, or to bre
c550: 61 6b 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20  ak stale locks. 
c560: 20 54 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63   The SQLite.** c
c570: 6f 72 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c  ore reserves all
c580: 20 6f 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68   opcodes less th
c590: 61 6e 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f  an 100 for its o
c5a0: 77 6e 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51  wn use..** A [SQ
c5b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
c5c0: 54 41 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f  TATE | list of o
c5d0: 70 63 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61  pcodes] less tha
c5e0: 6e 20 31 30 30 20 69 73 20 61 76 61 69 6c 61 62  n 100 is availab
c5f0: 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  le..** Applicati
c600: 6f 6e 73 20 74 68 61 74 20 64 65 66 69 6e 65 20  ons that define 
c610: 61 20 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f  a custom xFileCo
c620: 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f  ntrol method sho
c630: 75 6c 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a  uld use opcodes.
c640: 2a 2a 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ** greater than 
c650: 31 30 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e  100 to avoid con
c660: 66 6c 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70  flicts.  VFS imp
c670: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
c680: 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
c690: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20  QLITE_NOTFOUND] 
c6a0: 66 6f 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  for file control
c6b0: 20 6f 70 63 6f 64 65 73 20 74 68 61 74 20 74 68   opcodes that th
c6c0: 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63  ey do not.** rec
c6d0: 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  ognize..**.** Th
c6e0: 65 20 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20  e xSectorSize() 
c6f0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74  method returns t
c700: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f  he sector size o
c710: 66 20 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20  f the.** device 
c720: 74 68 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74  that underlies t
c730: 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65  he file.  The se
c740: 63 74 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65  ctor size is the
c750: 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74  .** minimum writ
c760: 65 20 74 68 61 74 20 63 61 6e 20 62 65 20 70 65  e that can be pe
c770: 72 66 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20  rformed without 
c780: 64 69 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74  disturbing.** ot
c790: 68 65 72 20 62 79 74 65 73 20 69 6e 20 74 68 65  her bytes in the
c7a0: 20 66 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76   file.  The xDev
c7b0: 69 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69  iceCharacteristi
c7c0: 63 73 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72  cs().** method r
c7d0: 65 74 75 72 6e 73 20 61 20 62 69 74 20 76 65 63  eturns a bit vec
c7e0: 74 6f 72 20 64 65 73 63 72 69 62 69 6e 67 20 62  tor describing b
c7f0: 65 68 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a  ehaviors of the.
c800: 2a 2a 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65  ** underlying de
c810: 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  vice:.**.** <ul>
c820: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c830: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a  _IOCAP_ATOMIC].*
c840: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
c850: 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a  OCAP_ATOMIC512].
c860: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c870: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a  IOCAP_ATOMIC1K].
c880: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c890: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a  IOCAP_ATOMIC2K].
c8a0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c8b0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a  IOCAP_ATOMIC4K].
c8c0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c8d0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a  IOCAP_ATOMIC8K].
c8e0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
c8f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d  IOCAP_ATOMIC16K]
c900: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
c910: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b  _IOCAP_ATOMIC32K
c920: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
c930: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34  E_IOCAP_ATOMIC64
c940: 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  K].** <li> [SQLI
c950: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
c960: 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  PEND].** <li> [S
c970: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55  QLITE_IOCAP_SEQU
c980: 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  ENTIAL].** </ul>
c990: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54  .**.** The SQLIT
c9a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70  E_IOCAP_ATOMIC p
c9b0: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
c9c0: 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66  at all writes of
c9d0: 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65  .** any size are
c9e0: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
c9f0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
ca00: 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d  Cnnn values.** m
ca10: 65 61 6e 20 74 68 61 74 20 77 72 69 74 65 73 20  ean that writes 
ca20: 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61  of blocks that a
ca30: 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20  re nnn bytes in 
ca40: 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20  size and.** are 
ca50: 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64  aligned to an ad
ca60: 64 72 65 73 73 20 77 68 69 63 68 20 69 73 20 61  dress which is a
ca70: 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70  n integer multip
ca80: 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65  le of.** nnn are
ca90: 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51   atomic.  The SQ
caa0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f  LITE_IOCAP_SAFE_
cab0: 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61  APPEND value mea
cac0: 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20  ns.** that when 
cad0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
cae0: 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20   to a file, the 
caf0: 64 61 74 61 20 69 73 20 61 70 70 65 6e 64 65 64  data is appended
cb00: 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74  .** first then t
cb10: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66  he size of the f
cb20: 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c  ile is extended,
cb30: 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68 65 72   never the other
cb40: 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20  .** way around. 
cb50: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
cb60: 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f  P_SEQUENTIAL pro
cb70: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
cb80: 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  .** information 
cb90: 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69  is written to di
cba0: 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f  sk in the same o
cbb0: 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a  rder as calls.**
cbc0: 20 74 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a   to xWrite()..**
cbd0: 0a 2a 2a 20 49 66 20 78 52 65 61 64 28 29 20 72  .** If xRead() r
cbe0: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f  eturns SQLITE_IO
cbf0: 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69  ERR_SHORT_READ i
cc00: 74 20 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c  t must also fill
cc10: 0a 2a 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61  .** in the unrea
cc20: 64 20 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68  d portions of th
cc30: 65 20 62 75 66 66 65 72 20 77 69 74 68 20 7a 65  e buffer with ze
cc40: 72 6f 73 2e 20 20 41 20 56 46 53 20 74 68 61 74  ros.  A VFS that
cc50: 0a 2a 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72  .** fails to zer
cc60: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
cc70: 64 73 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f  ds might seem to
cc80: 20 77 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c   work.  However,
cc90: 0a 2a 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a  .** failure to z
cca0: 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72  ero-fill short r
ccb0: 65 61 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75  eads will eventu
ccc0: 61 6c 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20  ally lead to.** 
ccd0: 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
cce0: 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ion..*/.typedef 
ccf0: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69  struct sqlite3_i
cd00: 6f 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65  o_methods sqlite
cd10: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  3_io_methods;.st
cd20: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
cd30: 6d 65 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20  methods {.  int 
cd40: 69 56 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20  iVersion;.  int 
cd50: 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  (*xClose)(sqlite
cd60: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
cd70: 28 2a 78 52 65 61 64 29 28 73 71 6c 69 74 65 33  (*xRead)(sqlite3
cd80: 5f 66 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69  _file*, void*, i
cd90: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
cda0: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
cdb0: 20 69 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73   int (*xWrite)(s
cdc0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f  qlite3_file*, co
cdd0: 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69  nst void*, int i
cde0: 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  Amt, sqlite3_int
cdf0: 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74  64 iOfst);.  int
ce00: 20 28 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71   (*xTruncate)(sq
ce10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c  lite3_file*, sql
ce20: 69 74 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29  ite3_int64 size)
ce30: 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
ce40: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
ce50: 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e  int flags);.  in
ce60: 74 20 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73  t (*xFileSize)(s
ce70: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71  qlite3_file*, sq
ce80: 6c 69 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69  lite3_int64 *pSi
ce90: 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f  ze);.  int (*xLo
cea0: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
ceb0: 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28  *, int);.  int (
cec0: 2a 78 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65  *xUnlock)(sqlite
ced0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20  3_file*, int);. 
cee0: 20 69 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73   int (*xCheckRes
cef0: 65 72 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74  ervedLock)(sqlit
cf00: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70  e3_file*, int *p
cf10: 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28  ResOut);.  int (
cf20: 2a 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73  *xFileControl)(s
cf30: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
cf40: 74 20 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67  t op, void *pArg
cf50: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74  );.  int (*xSect
cf60: 6f 72 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  orSize)(sqlite3_
cf70: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
cf80: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
cf90: 69 73 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f  istics)(sqlite3_
cfa0: 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74  file*);.  /* Met
cfb0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76  hods above are v
cfc0: 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e  alid for version
cfd0: 20 31 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53   1 */.  int (*xS
cfe0: 68 6d 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  hmMap)(sqlite3_f
cff0: 69 6c 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69  ile*, int iPg, i
d000: 6e 74 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f  nt pgsz, int, vo
d010: 69 64 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a  id volatile**);.
d020: 20 20 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b    int (*xShmLock
d030: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
d040: 20 69 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74   int offset, int
d050: 20 6e 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a   n, int flags);.
d060: 20 20 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72    void (*xShmBar
d070: 72 69 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69  rier)(sqlite3_fi
d080: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  le*);.  int (*xS
d090: 68 6d 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33  hmUnmap)(sqlite3
d0a0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65  _file*, int dele
d0b0: 74 65 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65  teFlag);.  /* Me
d0c0: 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20  thods above are 
d0d0: 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f  valid for versio
d0e0: 6e 20 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69  n 2 */.  /* Addi
d0f0: 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d  tional methods m
d100: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
d110: 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a  uture releases *
d120: 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
d130: 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46  3REF: Standard F
d140: 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f  ile Control Opco
d150: 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  des.**.** These 
d160: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
d170: 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f  s are opcodes fo
d180: 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  r the xFileContr
d190: 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20  ol method.** of 
d1a0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f  the [sqlite3_io_
d1b0: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20  methods] object 
d1c0: 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c  and for the [sql
d1d0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
d1e0: 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63  l()].** interfac
d1f0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  e..**.** The [SQ
d200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
d210: 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20  TATE] opcode is 
d220: 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67 69  used for debuggi
d230: 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63  ng.  This.** opc
d240: 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20 78  ode causes the x
d250: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
d260: 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65 20  od to write the 
d270: 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66  current state of
d280: 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e  .** the lock (on
d290: 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  e of [SQLITE_LOC
d2a0: 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45  K_NONE], [SQLITE
d2b0: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
d2c0: 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  * [SQLITE_LOCK_R
d2d0: 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54  ESERVED], [SQLIT
d2e0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c  E_LOCK_PENDING],
d2f0: 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b   or [SQLITE_LOCK
d300: 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20  _EXCLUSIVE]).** 
d310: 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  into an integer 
d320: 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61 72  that the pArg ar
d330: 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f  gument points to
d340: 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74  . This capabilit
d350: 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72  y.** is used dur
d360: 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20  ing testing and 
d370: 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65  only needs to be
d380: 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20   supported when 
d390: 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69  SQLITE_TEST.** i
d3a0: 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75  s defined..** <u
d3b0: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  l>.** <li>[[SQLI
d3c0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
d3d0: 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  NT]].** The [SQL
d3e0: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
d3f0: 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  INT] opcode is u
d400: 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74 6f  sed by SQLite to
d410: 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a 2a   give the VFS.**
d420: 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f 66   layer a hint of
d430: 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20 64   how large the d
d440: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c  atabase file wil
d450: 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75 72  l grow to be dur
d460: 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72 65  ing the.** curre
d470: 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20  nt transaction. 
d480: 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e 6f   This hint is no
d490: 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20  t guaranteed to 
d4a0: 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74 20  be accurate but 
d4b0: 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20 63  it.** is often c
d4c0: 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65 72  lose.  The under
d4d0: 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74 20  lying VFS might 
d4e0: 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c 6c  choose to preall
d4f0: 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a 2a  ocate database.*
d500: 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61 73  * file space bas
d510: 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74 20  ed on this hint 
d520: 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c 70  in order to help
d530: 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20 64   writes to the d
d540: 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20  atabase.** file 
d550: 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a  run faster..**.*
d560: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
d570: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d  CNTL_CHUNK_SIZE]
d580: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
d590: 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a  _FCNTL_CHUNK_SIZ
d5a0: 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  E] opcode is use
d5b0: 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61  d to request tha
d5c0: 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74  t the VFS.** ext
d5d0: 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74  ends and truncat
d5e0: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
d5f0: 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f  file in chunks o
d600: 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69  f a size specifi
d610: 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65  ed.** by the use
d620: 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72  r. The fourth ar
d630: 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74  gument to [sqlit
d640: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
d650: 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f  )] should .** po
d660: 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  int to an intege
d670: 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e  r (type int) con
d680: 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20  taining the new 
d690: 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73  chunk-size to us
d6a0: 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d  e.** for the nom
d6b0: 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e  inated database.
d6c0: 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61   Allocating data
d6d0: 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20  base file space 
d6e0: 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e  in large.** chun
d6f0: 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61  ks (say 1MB at a
d700: 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75   time), may redu
d710: 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66  ce file-system f
d720: 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64  ragmentation and
d730: 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66  .** improve perf
d740: 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20  ormance on some 
d750: 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c  systems..**.** <
d760: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
d770: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d  L_FILE_POINTER]]
d780: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
d790: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
d7a0: 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ER] opcode is us
d7b0: 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70  ed to obtain a p
d7c0: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
d7d0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
d7e0: 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65  object associate
d7f0: 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75  d with a particu
d800: 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  lar database.** 
d810: 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65  connection.  See
d820: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
d830: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f  le_control()] do
d840: 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a  cumentation for.
d850: 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
d860: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
d870: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d880: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
d890: 5d 5d 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c  ]].** ^(The [SQL
d8a0: 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f  ITE_FCNTL_SYNC_O
d8b0: 4d 49 54 54 45 44 5d 20 6f 70 63 6f 64 65 20 69  MITTED] opcode i
d8c0: 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74 65  s generated inte
d8d0: 72 6e 61 6c 6c 79 20 62 79 0a 2a 2a 20 53 51 4c  rnally by.** SQL
d8e0: 69 74 65 20 61 6e 64 20 73 65 6e 74 20 74 6f 20  ite and sent to 
d8f0: 61 6c 6c 20 56 46 53 65 73 20 69 6e 20 70 6c 61  all VFSes in pla
d900: 63 65 20 6f 66 20 61 20 63 61 6c 6c 20 74 6f 20  ce of a call to 
d910: 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68 6f 64  the xSync method
d920: 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 64 61 74  .** when the dat
d930: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
d940: 20 68 61 73 20 5b 50 52 41 47 4d 41 20 73 79 6e   has [PRAGMA syn
d950: 63 68 72 6f 6e 6f 75 73 5d 20 73 65 74 20 74 6f  chronous] set to
d960: 20 4f 46 46 2e 29 5e 0a 2a 2a 20 53 6f 6d 65 20   OFF.)^.** Some 
d970: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
d980: 73 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e  s need this sign
d990: 61 6c 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f  al in order to o
d9a0: 70 65 72 61 74 65 20 63 6f 72 72 65 63 74 6c 79  perate correctly
d9b0: 0a 2a 2a 20 77 68 65 6e 20 5b 50 52 41 47 4d 41  .** when [PRAGMA
d9c0: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50   synchronous | P
d9d0: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
d9e0: 73 3d 4f 46 46 5d 20 69 73 20 73 65 74 2c 20 62  s=OFF] is set, b
d9f0: 75 74 20 6d 6f 73 74 20 0a 2a 2a 20 56 46 53 65  ut most .** VFSe
da00: 73 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68  s do not need th
da10: 69 73 20 73 69 67 6e 61 6c 20 61 6e 64 20 73 68  is signal and sh
da20: 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20 69 67  ould silently ig
da30: 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f 64 65  nore this opcode
da40: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
da50: 73 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c  s should not cal
da60: 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  l [sqlite3_file_
da70: 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20  control()] with 
da80: 74 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61  this.** opcode a
da90: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64  s doing so may d
daa0: 69 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61  isrupt the opera
dab0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63  tion of the spec
dac0: 69 61 6c 69 7a 65 64 20 56 46 53 65 73 0a 2a 2a  ialized VFSes.**
dad0: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
dae0: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
daf0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
db00: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
db10: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
db20: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
db30: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
db40: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
db50: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
db60: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
db70: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
db80: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
db90: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
dba0: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
dbb0: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
dbc0: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
dbd0: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
dbe0: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
dbf0: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
dc00: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
dc10: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
dc20: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
dc30: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
dc40: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
dc50: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
dc60: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
dc70: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
dc80: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
dc90: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
dca0: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
dcb0: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
dcc0: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
dcd0: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
dce0: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
dcf0: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
dd00: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
dd10: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
dd20: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
dd30: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
dd40: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
dd50: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
dd60: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
dd70: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
dd80: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
dd90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
dda0: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
ddb0: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
ddc0: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
ddd0: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
dde0: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
ddf0: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
de00: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
de10: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
de20: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
de30: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
de40: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
de50: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
de60: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
de70: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
de80: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
de90: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
dea0: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
deb0: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
dec0: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
ded0: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
dee0: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
def0: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
df00: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
df10: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
df20: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
df30: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
df40: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
df50: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
df60: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
df70: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
df80: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
df90: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
dfa0: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
dfb0: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
dfc0: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
dfd0: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
dfe0: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
dff0: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
e000: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
e010: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
e020: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
e030: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
e040: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
e050: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
e060: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
e070: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
e080: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
e090: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
e0a0: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
e0b0: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
e0c0: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
e0d0: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
e0e0: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
e0f0: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
e100: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
e110: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
e120: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
e130: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
e140: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
e150: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
e160: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
e170: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
e180: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
e190: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
e1a0: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
e1b0: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
e1c0: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
e1d0: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
e1e0: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
e1f0: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
e200: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
e210: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
e220: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
e230: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
e240: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
e250: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
e260: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
e270: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
e280: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
e290: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
e2a0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
e2b0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
e2c0: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
e2d0: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
e2e0: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
e2f0: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
e300: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
e310: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
e320: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
e330: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
e340: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
e350: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
e360: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
e370: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
e380: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
e390: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
e3a0: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
e3b0: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
e3c0: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
e3d0: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
e3e0: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
e3f0: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
e400: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
e410: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
e420: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
e430: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
e440: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
e450: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
e460: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
e470: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
e480: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
e490: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
e4a0: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
e4b0: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
e4c0: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
e4d0: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
e4e0: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
e4f0: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
e500: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
e510: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
e520: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
e530: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
e540: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
e550: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
e560: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
e570: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
e580: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
e590: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
e5a0: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
e5b0: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
e5c0: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
e5d0: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
e5e0: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
e5f0: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
e600: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
e610: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
e620: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
e630: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
e640: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
e650: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
e660: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
e670: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
e680: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
e690: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
e6a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
e6b0: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
e6c0: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
e6d0: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
e6e0: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
e6f0: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
e700: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
e710: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
e720: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
e730: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
e740: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
e750: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
e760: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
e770: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
e780: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
e790: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
e7a0: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
e7b0: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
e7c0: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
e7d0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
e7e0: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
e7f0: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
e800: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
e810: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
e820: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
e830: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
e840: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
e850: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
e860: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
e870: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
e880: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
e890: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
e8a0: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
e8b0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
e8c0: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
e8d0: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
e8e0: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
e8f0: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
e900: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
e910: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
e920: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
e930: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
e940: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
e950: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
e960: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
e970: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
e980: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
e990: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
e9a0: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
e9b0: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
e9c0: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
e9d0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
e9e0: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
e9f0: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
ea00: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
ea10: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
ea20: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
ea30: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
ea40: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
ea50: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
ea60: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
ea70: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
ea80: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
ea90: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
eaa0: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
eab0: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
eac0: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
ead0: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
eae0: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
eaf0: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
eb00: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
eb10: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
eb20: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
eb30: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
eb40: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
eb50: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
eb60: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
eb70: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
eb80: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
eb90: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
eba0: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
ebb0: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
ebc0: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
ebd0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
ebe0: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
ebf0: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
ec00: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
ec10: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
ec20: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
ec30: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
ec40: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
ec50: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
ec60: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
ec70: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
ec80: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
ec90: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
eca0: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
ecb0: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
ecc0: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
ecd0: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
ece0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
ecf0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
ed00: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
ed10: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
ed20: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
ed30: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
ed40: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
ed50: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
ed60: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
ed70: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
ed80: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
ed90: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49  d statement.  ^I
eda0: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
edb0: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
edc0: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
edd0: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
ede0: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
edf0: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
ee00: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
ee10: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
ee20: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
ee30: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
ee40: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
ee50: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
ee60: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
ee70: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
ee80: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
ee90: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
eea0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
eeb0: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
eec0: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
eed0: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
eee0: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
eef0: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
ef00: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
ef10: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
ef20: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
ef30: 6d 65 6e 74 73 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  ments..** </ul>.
ef40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
ef50: 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54  E_FCNTL_LOCKSTAT
ef60: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
ef70: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
ef80: 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49  _GET_LOCKPROXYFI
ef90: 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20 32  LE             2
efa0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
efb0: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
efc0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a  E             3.
efd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
efe0: 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20 20 20  AST_ERRNO       
eff0: 20 20 20 20 20 20 20 20 20 20 20 20 20 34 0a 23               4.#
f000: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
f010: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20  NTL_SIZE_HINT   
f020: 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
f030: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
f040: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20  TL_CHUNK_SIZE   
f050: 20 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65             6.#de
f060: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
f070: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20  L_FILE_POINTER  
f080: 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65 66            7.#def
f090: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
f0a0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
f0b0: 20 20 20 20 20 20 20 20 20 38 0a 23 64 65 66 69           8.#defi
f0c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
f0d0: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 20 20  WIN32_AV_RETRY  
f0e0: 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e          9.#defin
f0f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
f100: 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20 20 20  ERSIST_WAL      
f110: 20 20 20 20 20 20 31 30 0a 23 64 65 66 69 6e 65        10.#define
f120: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56   SQLITE_FCNTL_OV
f130: 45 52 57 52 49 54 45 20 20 20 20 20 20 20 20 20  ERWRITE         
f140: 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e 65 20       11.#define 
f150: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53  SQLITE_FCNTL_VFS
f160: 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20 20 20  NAME            
f170: 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65 20 53      12.#define S
f180: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45  QLITE_FCNTL_POWE
f190: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
f1a0: 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20 53 51     13.#define SQ
f1b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
f1c0: 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
f1d0: 20 20 31 34 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    14../*.** CAPI
f1e0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
f1f0: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
f200: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
f210: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
f220: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
f230: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
f240: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
f250: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
f260: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
f270: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
f280: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
f290: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
f2a0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
f2b0: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
f2c0: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
f2d0: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
f2e0: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
f2f0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
f300: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
f310: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
f320: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
f330: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
f340: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
f350: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
f360: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
f370: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
f380: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
f390: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
f3a0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
f3b0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
f3c0: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
f3d0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
f3e0: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
f3f0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
f400: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
f410: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
f420: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
f430: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
f440: 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65  le system".  See
f450: 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56  .** the [VFS | V
f460: 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  FS documentation
f470: 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e  ] for further in
f480: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
f490: 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   The value of th
f4a0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
f4b0: 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20   is initially 1 
f4c0: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
f4d0: 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76  r in.** future v
f4e0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
f4f0: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
f500: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
f510: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
f520: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
f530: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
f540: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e  is increased.  N
f550: 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72  ote that the str
f560: 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65  ucture.** of the
f570: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
f580: 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74  ect changes in t
f590: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
f5a0: 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  etween.** SQLite
f5b0: 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61   version 3.5.9 a
f5c0: 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74  nd 3.6.0 and yet
f5d0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
f5e0: 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d  eld was not.** m
f5f0: 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  odified..**.** T
f600: 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c  he szOsFile fiel
f610: 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  d is the size of
f620: 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20   the subclassed 
f630: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a  [sqlite3_file].*
f640: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64  * structure used
f650: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d   by this VFS.  m
f660: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65  xPathname is the
f670: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
f680: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65  of.** a pathname
f690: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a   in this VFS..**
f6a0: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73  .** Registered s
f6b0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
f6c0: 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61  ts are kept on a
f6d0: 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72   linked list for
f6e0: 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e  med by.** the pN
f6f0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ext pointer.  Th
f700: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  e [sqlite3_vfs_r
f710: 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e  egister()].** an
f720: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  d [sqlite3_vfs_u
f730: 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74  nregister()] int
f740: 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74  erfaces manage t
f750: 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61  his list.** in a
f760: 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79   thread-safe way
f770: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
f780: 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65  vfs_find()] inte
f790: 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65  rface.** searche
f7a0: 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69  s the list.  Nei
f7b0: 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  ther the applica
f7c0: 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68  tion code nor th
f7d0: 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65  e VFS.** impleme
f7e0: 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  ntation should u
f7f0: 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  se the pNext poi
f800: 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
f810: 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74  pNext field is t
f820: 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e  he only field in
f830: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
f840: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68  .** structure th
f850: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  at SQLite will e
f860: 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c  ver modify.  SQL
f870: 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63  ite will only ac
f880: 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66  cess.** or modif
f890: 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69  y this field whi
f8a0: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
f8b0: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
f8c0: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
f8d0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
f8e0: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
f8f0: 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65  thing within the
f900: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
f910: 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20  object once the 
f920: 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20  object has been 
f930: 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a  registered..**.*
f940: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
f950: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
f960: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
f970: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
f980: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
f990: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
f9a0: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  odules..**.** [[
f9b0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
f9c0: 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  n]].** ^SQLite g
f9d0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
f9e0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
f9f0: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
fa00: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
fa10: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
fa20: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
fa30: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
fa40: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
fa50: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
fa60: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
fa70: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
fa80: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
fa90: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
faa0: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
fab0: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
fac0: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
fad0: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
fae0: 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65  .** 11 alphanume
faf0: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
fb00: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
fb10: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
fb20: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
fb30: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
fb40: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
fb50: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
fb60: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
fb70: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
fb80: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
fb90: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
fba0: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
fbb0: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
fbc0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
fbd0: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
fbe0: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
fbf0: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
fc00: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
fc10: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
fc20: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
fc30: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
fc40: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
fc50: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
fc60: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
fc70: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
fc80: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
fc90: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
fca0: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
fcb0: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
fcc0: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
fcd0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
fce0: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
fcf0: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
fd00: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
fd10: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
fd20: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
fd30: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
fd40: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
fd50: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
fd60: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
fd70: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
fd80: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
fd90: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
fda0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
fdb0: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
fdc0: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
fdd0: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
fde0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
fdf0: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
fe00: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
fe10: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
fe20: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
fe30: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
fe40: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
fe50: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
fe60: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
fe70: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
fe80: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
fe90: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
fea0: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
feb0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
fec0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
fed0: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
fee0: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
fef0: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
ff00: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
ff10: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
ff20: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
ff30: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
ff40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
ff50: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
ff60: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
ff70: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
ff80: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
ff90: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
ffa0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ffb0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
ffc0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ffd0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
ffe0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
fff0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
10000 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
10010 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
10020 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
10030 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
10040 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
10050 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
10060 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
10070 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
10080 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
10090 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
100a0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
100b0 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
100c0 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
100d0 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
100e0 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
100f0 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
10100 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
10110 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
10120 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
10130 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
10140 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
10150 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
10160 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
10170 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
10180 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
10190 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
101a0 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
101b0 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
101c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
101d0 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
101e0 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
101f0 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
10200 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
10210 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
10220 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
10230 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
10240 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
10250 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
10260 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
10270 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
10280 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
10290 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
102a0 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
102b0 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
102c0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
102d0 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
102e0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
102f0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
10300 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
10310 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
10320 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
10330 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
10340 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
10350 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
10360 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
10370 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
10380 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
10390 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
103a0 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
103b0 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
103c0 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
103d0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
103e0 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
103f0 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
10400 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
10410 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
10420 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
10430 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
10440 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
10450 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
10460 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
10470 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
10480 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
10490 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
104a0 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
104b0 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
104c0 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
104d0 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
104e0 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
104f0 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
10500 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
10510 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
10520 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
10530 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
10540 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
10550 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
10560 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
10570 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
10580 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
10590 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
105a0 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
105b0 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
105c0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
105d0 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
105e0 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
105f0 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
10600 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
10610 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
10620 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
10630 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
10640 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
10650 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
10660 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
10670 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
10680 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
10690 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
106a0 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
106b0 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
106c0 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
106d0 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
106e0 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
106f0 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
10700 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
10710 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
10720 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
10730 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
10740 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
10750 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
10760 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
10770 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
10780 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
10790 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
107a0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
107b0 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
107c0 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
107d0 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
107e0 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41  [[sqlite3_vfs.xA
107f0 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20  ccess]].** ^The 
10800 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
10810 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
10820 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
10830 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
10840 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
10850 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
10860 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
10870 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
10880 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
10890 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
108a0 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
108b0 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
108c0 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
108d0 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
108e0 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
108f0 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
10900 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
10910 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
10920 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
10930 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
10940 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
10950 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
10960 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
10970 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
10980 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
10990 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
109a0 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
109b0 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
109c0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
109d0 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
109e0 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
109f0 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
10a00 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
10a10 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
10a20 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
10a30 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
10a40 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
10a50 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
10a60 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
10a70 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
10a80 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
10a90 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
10aa0 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
10ab0 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
10ac0 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
10ad0 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
10ae0 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
10af0 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  ), xCurrentTime(
10b00 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
10b10 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e  imeInt64().** in
10b20 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74  terfaces are not
10b30 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74   strictly a part
10b40 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74   of the filesyst
10b50 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65  em, but they are
10b60 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  .** included in 
10b70 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72  the VFS structur
10b80 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65  e for completene
10b90 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ss..** The xRand
10ba0 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f  omness() functio
10bb0 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  n attempts to re
10bc0 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65  turn nBytes byte
10bd0 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61  s.** of good-qua
10be0 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20  lity randomness 
10bf0 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
10c00 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a  return value is.
10c10 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75  ** the actual nu
10c20 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
10c30 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
10c40 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c  ined..** The xSl
10c50 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
10c60 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ses the calling 
10c70 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20  thread to sleep 
10c80 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20  for at.** least 
10c90 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
10ca0 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e  croseconds given
10cb0 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  .  ^The xCurrent
10cc0 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
10cd0 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
10ce0 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
10cf0 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
10d00 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a  e and time as.**
10d10 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
10d20 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65  t value..** ^The
10d30 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
10d40 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  64() method retu
10d50 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67  rns, as an integ
10d60 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a  er, the Julian.*
10d70 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c  * Day Number mul
10d80 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30  tiplied by 86400
10d90 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20  000 (the number 
10da0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
10db0 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72  in .** a 24-hour
10dc0 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c   day).  .** ^SQL
10dd0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
10de0 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
10df0 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67  64() method to g
10e00 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  et the current.*
10e10 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  * date and time 
10e20 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69  if that method i
10e30 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20  s available (if 
10e40 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72  iVersion is 2 or
10e50 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64   .** greater and
10e60 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
10e70 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
10e80 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c  L) and will fall
10e90 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72   back.** to xCur
10ea0 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43  rentTime() if xC
10eb0 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
10ec0 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  ) is unavailable
10ed0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65  ..**.** ^The xSe
10ee0 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78  tSystemCall(), x
10ef0 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  GetSystemCall(),
10f00 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d   and xNestSystem
10f10 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  Call() interface
10f20 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65  s.** are not use
10f30 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20  d by the SQLite 
10f40 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74  core.  These opt
10f50 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ional interfaces
10f60 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a   are provided.**
10f70 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74   by some VFSes t
10f80 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73  o facilitate tes
10f90 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20  ting of the VFS 
10fa0 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64  code. By overrid
10fb0 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63  ing .** system c
10fc0 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69  alls with functi
10fd0 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f  ons under its co
10fe0 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72  ntrol, a test pr
10ff0 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d  ogram can.** sim
11000 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64  ulate faults and
11010 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e   error condition
11020 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68  s that would oth
11030 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63  erwise be diffic
11040 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73  ult.** or imposs
11050 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20  ible to induce. 
11060 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74   The set of syst
11070 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61  em calls that ca
11080 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a  n be overridden.
11090 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f  ** varies from o
110a0 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65  ne VFS to anothe
110b0 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20  r, and from one 
110c0 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73  version of the s
110d0 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a  ame VFS to the.*
110e0 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
110f0 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74  tions that use t
11100 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
11110 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64  must be prepared
11120 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61   for any.** or a
11130 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ll of these inte
11140 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c  rfaces to be NUL
11150 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62  L or for their b
11160 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67  ehavior to chang
11170 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65  e.** from one re
11180 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78  lease to the nex
11190 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
111a0 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70   must not attemp
111b0 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61  t to access.** a
111c0 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68  ny of these meth
111d0 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73  ods if the iVers
111e0 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69  ion of the VFS i
111f0 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a  s less than 3..*
11200 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
11210 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
11220 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65  ite3_vfs;.typede
11230 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
11240 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f  _syscall_ptr)(vo
11250 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  id);.struct sqli
11260 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
11270 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
11280 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
11290 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
112a0 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a   (currently 3) *
112b0 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
112c0 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
112d0 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
112e0 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
112f0 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
11300 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
11310 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
11320 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
11330 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
11340 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
11350 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
11360 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
11370 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
11380 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
11390 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
113a0 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
113b0 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
113c0 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
113d0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
113e0 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
113f0 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
11400 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
11410 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
11420 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
11430 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
11440 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
11450 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
11460 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
11470 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
11480 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
11490 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
114a0 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
114b0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
114c0 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
114d0 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
114e0 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
114f0 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
11500 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
11510 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
11520 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
11530 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
11540 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
11550 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
11560 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
11570 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
11580 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
11590 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
115a0 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28  rrMsg);.  void (
115b0 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
115c0 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
115d0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
115e0 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f  ol))(void);.  vo
115f0 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
11600 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
11610 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
11620 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
11630 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
11640 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
11650 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
11660 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
11670 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
11680 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
11690 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
116a0 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
116b0 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
116c0 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
116d0 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
116e0 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
116f0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
11700 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f  e in version 1 o
11710 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
11720 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66   object.  ** def
11730 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20  inition.  Those 
11740 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20  that follow are 
11750 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e  added in version
11760 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f   2 or later.  */
11770 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
11780 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69  tTimeInt64)(sqli
11790 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65  te3_vfs*, sqlite
117a0 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a  3_int64*);.  /*.
117b0 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
117c0 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
117d0 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f  rsions 1 and 2 o
117e0 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
117f0 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68   object..  ** Th
11800 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f  ose below are fo
11810 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20  r version 3 and 
11820 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20  greater..  */.  
11830 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d  int (*xSetSystem
11840 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
11850 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
11860 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
11870 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73  yscall_ptr);.  s
11880 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
11890 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43  tr (*xGetSystemC
118a0 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
118b0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
118c0 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63  Name);.  const c
118d0 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74  har *(*xNextSyst
118e0 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
118f0 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
11900 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20   *zName);.  /*. 
11910 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
11920 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
11930 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20  sions 1 through 
11940 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  3 of the sqlite_
11950 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
11960 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
11970 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
11980 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
11990 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
119a0 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
119b0 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
119c0 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a   this happens. .
119d0 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43    */.};../*.** C
119e0 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
119f0 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
11a00 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
11a10 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
11a20 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
11a30 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
11a40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
11a50 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
11a60 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
11a70 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
11a80 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
11a90 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
11aa0 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
11ab0 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
11ac0 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
11ad0 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
11ae0 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
11af0 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
11b00 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
11b10 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
11b20 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
11b30 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
11b40 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
11b50 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
11b60 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
11b70 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74  the named direct
11b80 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64  ory is both read
11b90 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
11ba0 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77  e.** (in other w
11bb0 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63  ords, if files c
11bc0 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d  an be added, rem
11bd0 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65  oved, and rename
11be0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
11bf0 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54  directory)..** T
11c00 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
11c10 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74  _READWRITE const
11c20 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ant is currently
11c30 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68   used only by th
11c40 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65  e.** [temp_store
11c50 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
11c60 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20  a], though this 
11c70 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20  could change in 
11c80 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
11c90 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
11ca0 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
11cb0 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
11cc0 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
11cd0 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
11ce0 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
11cf0 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54  able.  The SQLIT
11d00 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f  E_ACCESS_READ co
11d10 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72  nstant is.** cur
11d20 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74  rently unused, t
11d30 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62  hough it might b
11d40 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75  e used in a futu
11d50 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
11d60 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
11d70 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
11d80 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
11d90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
11da0 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20  ESS_READWRITE 1 
11db0 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41    /* Used by PRA
11dc0 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64  GMA temp_store_d
11dd0 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66  irectory */.#def
11de0 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
11df0 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20  S_READ      2   
11e00 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a  /* Unused */../*
11e10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
11e20 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d  ags for the xShm
11e30 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a  Lock VFS method.
11e40 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
11e50 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ger constants de
11e60 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73  fine the various
11e70 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69   locking operati
11e80 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62  ons.** allowed b
11e90 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  y the xShmLock m
11ea0 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65  ethod of [sqlite
11eb0 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20  3_io_methods].  
11ec0 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  The.** following
11ed0 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65   are the only le
11ee0 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  gal combinations
11ef0 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65   of flags to the
11f00 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  .** xShmLock met
11f10 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
11f20 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
11f30 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
11f40 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
11f50 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
11f60 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
11f70 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
11f80 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
11f90 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
11fa0 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
11fb0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
11fc0 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
11fd0 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
11fe0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65   </ul>.**.** Whe
11ff0 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65  n unlocking, the
12000 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20   same SHARED or 
12010 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d  EXCLUSIVE flag m
12020 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20  ust be supplied 
12030 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20  as.** was given 
12040 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  no the correspon
12050 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a  ding lock.  .**.
12060 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
12070 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73  method can trans
12080 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e  ition between un
12090 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45  locked and SHARE
120a0 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20  D or.** between 
120b0 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43  unlocked and EXC
120c0 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e  LUSIVE.  It cann
120d0 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  ot transition be
120e0 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20  tween SHARED.** 
120f0 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a  and EXCLUSIVE..*
12100 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12110 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  _SHM_UNLOCK     
12120 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
12130 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20  TE_SHM_LOCK     
12140 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
12150 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20  LITE_SHM_SHARED 
12160 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
12170 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
12180 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a  SIVE    8../*.**
12190 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d   CAPI3REF: Maxim
121a0 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65  um xShmLock inde
121b0 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d  x.**.** The xShm
121c0 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b  Lock method on [
121d0 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
121e0 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75  ds] may use valu
121f0 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  es.** between 0 
12200 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62  and this upper b
12210 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66  ound as its "off
12220 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  set" argument..*
12230 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
12240 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74  e will never att
12250 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20  empt to acquire 
12260 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20  or release a.** 
12270 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20  lock outside of 
12280 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64  this range.*/.#d
12290 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
122a0 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a  _NLOCK        8.
122b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
122c0 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
122d0 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
122e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
122f0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12300 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69  routine initiali
12310 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74  zes the.** SQLit
12320 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65  e library.  ^The
12330 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
12340 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
12350 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
12360 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
12370 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
12380 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12390 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ze()..** These r
123a0 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69  outines are desi
123b0 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70  gned to aid in p
123c0 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
123d0 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75  ation and.** shu
123e0 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65  tdown on embedde
123f0 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b  d systems.  Work
12400 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74  station applicat
12410 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ions using.** SQ
12420 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f  Lite normally do
12430 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76   not need to inv
12440 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68  oke either of th
12450 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
12460 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
12470 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12480 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
12490 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
124a0 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
124b0 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
124c0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
124d0 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
124e0 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
124f0 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
12500 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
12510 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
12520 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
12530 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
12540 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
12550 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12560 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66  .  ^(Only an eff
12570 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
12580 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
12590 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
125a0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
125b0 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
125c0 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
125d0 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
125e0 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
125f0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73  e3_shutdown() is
12600 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
12610 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68  call if it is th
12620 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20  e first.** call 
12630 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
12640 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20  own() since the 
12650 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  last sqlite3_ini
12660 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e  tialize().  ^(On
12670 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69  ly.** an effecti
12680 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ve call to sqlit
12690 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f  e3_shutdown() do
126a0 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c  es any deinitial
126b0 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20  ization..** All 
126c0 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c  other valid call
126d0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  s to sqlite3_shu
126e0 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d  tdown() are harm
126f0 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
12700 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12710 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e  _initialize() in
12720 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61  terface is threa
12730 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74  dsafe, but sqlit
12740 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
12750 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71   is not.  The sq
12760 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12770 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20   interface must 
12780 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66  only be called f
12790 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20  rom a.** single 
127a0 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65  thread.  All ope
127b0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
127c0 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65  ections] must be
127d0 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a   closed and all.
127e0 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ** other SQLite 
127f0 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62  resources must b
12800 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72  e deallocated pr
12810 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a  ior to invoking.
12820 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ** sqlite3_shutd
12830 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  own()..**.** Amo
12840 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
12850 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   ^sqlite3_initia
12860 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f  lize() will invo
12870 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
12880 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
12890 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68  rly, ^sqlite3_sh
128a0 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c  utdown().** will
128b0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
128c0 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
128d0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
128e0 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
128f0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
12900 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
12910 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d  ..** ^If for som
12920 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65  e reason, sqlite
12930 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
12940 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74  s unable to init
12950 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69  ialize.** the li
12960 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69  brary (perhaps i
12970 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  t is unable to a
12980 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64  llocate a needed
12990 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a   resource such.*
129a0 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74  * as a mutex) it
129b0 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72   returns an [err
129c0 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74  or code] other t
129d0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  han [SQLITE_OK].
129e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
129f0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
12a00 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
12a10 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
12a20 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
12a30 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
12a40 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
12a50 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
12a60 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
12a70 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
12a80 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12a90 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
12aa0 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
12ab0 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
12ac0 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
12ad0 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
12ae0 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
12af0 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
12b00 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
12b10 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
12b20 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
12b30 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
12b40 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
12b50 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77  * already.  ^How
12b60 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
12b70 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12b80 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   the [SQLITE_OMI
12b90 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63  T_AUTOINIT].** c
12ba0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
12bb0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
12bc0 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
12bd0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12be0 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
12bf0 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
12c00 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
12c10 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
12c20 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
12c30 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
12c40 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
12c50 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
12c60 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
12c70 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
12c80 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
12c90 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
12ca0 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
12cb0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
12cc0 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
12cd0 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
12ce0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
12cf0 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
12d00 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
12d10 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
12d20 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
12d30 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
12d40 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
12d50 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
12d60 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
12d70 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
12d80 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65  TOINIT] might be
12d90 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
12da0 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
12db0 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
12dc0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
12dd0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12de0 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
12df0 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
12e00 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
12e10 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
12e20 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
12e30 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
12e40 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
12e50 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
12e60 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
12e70 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
12e80 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
12e90 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
12ea0 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
12eb0 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
12ec0 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
12ed0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
12ee0 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
12ef0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
12f00 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
12f10 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
12f20 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
12f30 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
12f40 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
12f50 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
12f60 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
12f70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
12f80 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
12f90 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
12fa0 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
12fb0 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
12fc0 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
12fd0 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
12fe0 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
12ff0 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
13000 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
13010 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
13020 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
13030 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
13040 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
13050 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
13060 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
13070 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
13080 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
13090 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
130a0 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
130b0 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
130c0 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
130d0 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
130e0 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
130f0 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
13100 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
13110 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
13120 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
13130 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
13140 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73  or Unix, Windows
13150 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68  , or OS/2..** Wh
13160 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64  en [custom build
13170 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  s | built for ot
13180 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a  her platforms].*
13190 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51  * (using the [SQ
131a0 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d  LITE_OS_OTHER=1]
131b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
131c0 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
131d0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
131e0 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
131f0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
13200 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
13210 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
13220 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
13230 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
13240 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
13250 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
13260 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
13270 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
13280 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
13290 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
132a0 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65  success and some
132b0 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f   other [error co
132c0 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c  de] upon.** fail
132d0 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ure..*/.SQLITE_A
132e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  PI int sqlite3_i
132f0 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
13300 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
13310 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
13320 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
13330 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
13340 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51  s_init(void);.SQ
13350 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
13360 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
13370 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13380 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
13390 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
133a0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
133b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
133c0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
133d0 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
133e0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
133f0 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
13400 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
13410 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
13420 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
13430 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
13440 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
13450 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
13460 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
13470 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
13480 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
13490 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
134a0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
134b0 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
134c0 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
134d0 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
134e0 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
134f0 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
13500 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
13510 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
13520 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
13530 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
13540 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
13550 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
13560 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
13570 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
13580 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
13590 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
135a0 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
135b0 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
135c0 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
135d0 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
135e0 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
135f0 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
13600 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
13610 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
13620 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
13630 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
13640 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
13650 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
13660 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
13670 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
13680 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
13690 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
136a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
136b0 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
136c0 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
136d0 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
136e0 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
136f0 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
13700 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
13710 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
13720 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
13730 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
13740 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
13750 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
13760 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
13770 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
13780 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13790 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
137a0 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
137b0 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
137c0 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
137d0 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
137e0 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
137f0 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
13800 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
13810 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
13820 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
13830 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
13840 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
13850 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
13860 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
13870 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
13880 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
13890 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
138a0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
138b0 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
138c0 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
138d0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
138e0 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
138f0 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
13900 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
13910 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
13920 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
13930 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e   int sqlite3_con
13940 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
13950 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
13960 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
13970 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
13980 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
13990 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
139a0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
139b0 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
139c0 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
139d0 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
139e0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
139f0 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
13a00 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
13a10 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
13a20 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
13a30 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
13a40 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
13a50 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13a60 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
13a70 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
13a80 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
13a90 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
13aa0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
13ab0 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
13ac0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
13ad0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
13ae0 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
13af0 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
13b00 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
13b10 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
13b20 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
13b30 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
13b40 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
13b50 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
13b60 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
13b70 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
13b80 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
13b90 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
13ba0 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
13bb0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
13bc0 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
13bd0 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
13be0 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
13bf0 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
13c00 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  essful..*/.SQLIT
13c10 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
13c20 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
13c30 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
13c40 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
13c50 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
13c60 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
13c70 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
13c80 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
13c90 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
13ca0 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
13cb0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
13cc0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
13cd0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
13ce0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
13cf0 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
13d00 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
13d10 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
13d20 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
13d30 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
13d40 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
13d50 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
13d60 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
13d70 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
13d80 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
13d90 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
13da0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
13db0 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
13dc0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
13dd0 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
13de0 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
13df0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
13e00 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
13e10 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
13e20 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
13e30 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
13e40 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
13e50 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
13e60 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
13e70 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
13e80 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
13e90 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
13ea0 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
13eb0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
13ec0 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
13ed0 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
13ee0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
13ef0 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
13f00 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
13f10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
13f20 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
13f30 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
13f40 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
13f50 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
13f60 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
13f70 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
13f80 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
13f90 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
13fa0 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
13fb0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
13fc0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
13fd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
13fe0 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
13ff0 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
14000 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
14010 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
14020 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
14030 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
14040 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
14050 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
14060 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
14070 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
14080 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
14090 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
140a0 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
140b0 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
140c0 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
140d0 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
140e0 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
140f0 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
14100 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
14110 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
14120 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
14130 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
14140 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
14150 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
14160 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
14170 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
14180 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
14190 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
141a0 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
141b0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
141c0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
141d0 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
141e0 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
141f0 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
14200 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
14210 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
14220 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
14230 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
14240 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
14250 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
14260 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
14270 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
14280 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
14290 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
142a0 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
142b0 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
142c0 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
142d0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
142e0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
142f0 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
14300 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
14310 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
14320 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
14330 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
14340 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
14350 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
14360 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
14370 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
14380 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
14390 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
143a0 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
143b0 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
143c0 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
143d0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
143e0 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
143f0 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
14400 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14410 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
14420 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
14430 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
14440 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
14450 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
14460 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
14470 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
14480 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
14490 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
144a0 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
144b0 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
144c0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
144d0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
144e0 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
144f0 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
14500 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
14510 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
14520 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
14530 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
14540 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
14550 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
14560 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
14570 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
14580 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
14590 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
145a0 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
145b0 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
145c0 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
145d0 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
145e0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
145f0 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
14600 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
14610 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
14620 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
14630 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
14640 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
14650 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
14660 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
14670 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
14680 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
14690 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
146a0 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
146b0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
146c0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
146d0 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
146e0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
146f0 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
14700 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
14710 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
14720 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
14730 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
14740 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
14750 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
14760 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14770 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
14780 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
14790 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
147a0 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
147b0 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
147c0 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
147d0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
147e0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
147f0 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
14800 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
14810 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
14820 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
14830 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
14840 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
14850 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
14860 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
14870 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
14880 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
14890 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
148a0 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
148b0 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
148c0 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
148d0 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
148e0 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
148f0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
14900 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
14910 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
14920 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
14930 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
14940 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
14950 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
14960 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
14970 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
14980 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
14990 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
149a0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
149b0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
149c0 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
149d0 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
149e0 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
149f0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
14a00 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
14a10 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
14a20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
14a30 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
14a40 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
14a50 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
14a60 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
14a70 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
14a80 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
14a90 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
14aa0 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
14ab0 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
14ac0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
14ad0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
14ae0 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
14af0 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
14b00 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
14b10 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
14b20 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
14b30 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
14b40 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
14b50 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
14b60 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
14b70 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
14b80 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
14b90 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
14ba0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
14bb0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
14bc0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
14bd0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
14be0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
14bf0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
14c00 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
14c10 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
14c20 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
14c30 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
14c40 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
14c50 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
14c60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14c70 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
14c80 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
14c90 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
14ca0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
14cb0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14cc0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
14cd0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
14ce0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
14cf0 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
14d00 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
14d10 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
14d20 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
14d30 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
14d40 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
14d50 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
14d60 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
14d70 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
14d80 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
14d90 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
14da0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
14db0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
14dc0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
14dd0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
14de0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14df0 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
14e00 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
14e10 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
14e20 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
14e30 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
14e40 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
14e50 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
14e60 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
14e70 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
14e80 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
14e90 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
14ea0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
14eb0 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
14ec0 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
14ed0 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
14ee0 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
14ef0 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
14f00 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
14f10 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
14f20 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
14f30 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
14f40 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
14f50 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
14f60 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
14f70 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
14f80 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
14f90 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
14fa0 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
14fb0 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
14fc0 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
14fd0 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
14fe0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
14ff0 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
15000 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
15010 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
15020 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
15030 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
15040 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15050 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
15060 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15070 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
15080 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15090 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
150a0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
150b0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
150c0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
150d0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
150e0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
150f0 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
15100 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
15110 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
15120 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
15130 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
15140 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
15150 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
15160 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
15170 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
15180 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
15190 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
151a0 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
151b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
151c0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
151d0 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
151e0 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
151f0 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
15200 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
15210 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
15220 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
15230 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
15240 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
15250 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
15260 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
15270 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
15280 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15290 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
152a0 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
152b0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
152c0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
152d0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
152e0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
152f0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
15300 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
15310 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
15320 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
15330 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
15340 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
15350 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15360 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
15370 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
15380 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
15390 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
153a0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
153b0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
153c0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
153d0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
153e0 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
153f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
15400 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
15410 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
15420 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
15430 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
15440 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
15450 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
15460 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
15470 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
15480 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
15490 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
154a0 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
154b0 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
154c0 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
154d0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
154e0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
154f0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
15500 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
15510 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
15520 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
15530 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
15540 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
15550 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
15560 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
15570 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
15580 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
15590 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
155a0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
155b0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
155c0 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
155d0 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
155e0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
155f0 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
15600 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15610 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
15620 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
15630 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
15640 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
15650 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
15660 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
15670 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15680 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15690 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
156a0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
156b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
156c0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
156d0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
156e0 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
156f0 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
15700 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
15710 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
15720 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
15730 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
15740 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
15750 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
15760 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
15770 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
15780 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15790 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
157a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
157b0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
157c0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
157d0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
157e0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
157f0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
15800 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
15810 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
15820 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
15830 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
15840 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
15850 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
15860 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
15870 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
15880 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
15890 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
158a0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
158b0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
158c0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
158d0 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
158e0 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
158f0 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
15900 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
15910 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
15920 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
15930 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
15940 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15950 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
15960 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
15970 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15980 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
15990 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
159a0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
159b0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
159c0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
159d0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
159e0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
159f0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
15a00 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
15a10 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
15a20 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
15a30 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
15a40 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
15a50 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
15a60 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
15a70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
15a80 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
15a90 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
15aa0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
15ab0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
15ac0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
15ad0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
15ae0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
15af0 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
15b00 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15b10 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
15b20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
15b30 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
15b40 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
15b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
15b60 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
15b70 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
15b80 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
15b90 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
15ba0 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
15bb0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
15bc0 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
15bd0 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
15be0 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
15bf0 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
15c00 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
15c10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
15c20 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  ** statistics. ^
15c30 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
15c40 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
15c50 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c  cs are disabled,
15c60 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69   the .** followi
15c70 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
15c80 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
15c90 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
15ca0 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
15cb0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
15cc0 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
15cd0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
15ce0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
15cf0 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
15d00 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
15d10 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
15d20 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
15d30 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  s()].**   </ul>)
15d40 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
15d50 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
15d60 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
15d70 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
15d80 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
15d90 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
15da0 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
15db0 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
15dc0 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
15dd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
15de0 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
15df0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
15e00 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
15e10 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
15e20 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
15e30 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
15e40 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
15e50 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
15e60 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
15e70 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
15e80 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
15e90 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
15ea0 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
15eb0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
15ec0 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
15ed0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
15ee0 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
15ef0 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
15f00 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
15f10 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
15f20 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
15f30 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
15f40 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
15f50 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
15f60 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
15f70 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
15f80 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
15f90 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
15fa0 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
15fb0 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72  f 16..** The fir
15fc0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
15fd0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
15fe0 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
15ff0 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
16000 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
16010 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
16020 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
16030 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
16040 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66  two scratch buff
16050 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20  ers per thread. 
16060 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
16070 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20  be set to twice 
16080 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
16090 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
160a0 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69  hreads..** ^SQLi
160b0 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
160c0 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
160d0 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
160e0 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
160f0 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
16100 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
16110 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
16120 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
16130 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
16140 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
16150 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
16160 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16170 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
16180 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
16190 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
161a0 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
161b0 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
161c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
161d0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
161e0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
161f0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
16200 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
16210 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
16220 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
16230 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
16240 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
16250 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
16260 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
16270 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
16280 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
16290 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
162a0 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
162b0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
162c0 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
162d0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
162e0 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
162f0 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
16300 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
16310 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16320 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  HE2 option..** T
16330 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
16340 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
16350 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
16360 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69  er to 8-byte ali
16370 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
16380 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
16390 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
163a0 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
163b0 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
163c0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
163d0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
163e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
163f0 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
16400 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
16410 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
16420 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75  2 and 32768) plu
16430 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61  s a little extra
16440 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
16450 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
16460 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65  page header size
16470 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74   is 20 to 40 byt
16480 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a  es depending on.
16490 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68  ** the host arch
164a0 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69  itecture.  ^It i
164b0 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
164c0 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
164d0 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20  d memory,.** to 
164e0 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65  make sz a little
164f0 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65   too large.  The
16500 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
16510 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
16520 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
16530 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
16540 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
16550 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
16560 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
16570 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
16580 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16590 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
165a0 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
165b0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
165c0 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
165d0 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
165e0 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
165f0 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
16600 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
16610 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
16620 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
16630 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
16640 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
16650 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
16660 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
16670 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
16680 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  ** The pointer i
16690 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
166a0 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
166b0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
166c0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
166d0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
166e0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
166f0 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
16700 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
16710 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16720 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
16730 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
16740 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
16750 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
16760 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
16770 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
16780 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
16790 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
167a0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
167b0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
167c0 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
167d0 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
167e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
167f0 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
16800 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
16810 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
16820 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
16830 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
16840 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
16850 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
16860 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
16870 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
16880 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
16890 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
168a0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
168b0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
168c0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
168d0 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
168e0 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
168f0 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
16900 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
16910 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
16920 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
16930 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
16940 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
16950 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
16960 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
16970 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
16980 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
16990 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
169a0 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68  ot NULL and eith
169b0 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
169c0 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a  E_MEMSYS3] or.**
169d0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
169e0 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66  MEMSYS5] are def
169f0 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61  ined, then the a
16a00 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
16a10 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
16a20 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
16a30 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
16a40 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
16a50 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
16a60 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
16a70 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
16a80 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
16a90 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
16aa0 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
16ab0 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
16ac0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
16ad0 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
16ae0 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
16af0 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
16b00 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
16b10 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
16b20 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
16b30 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
16b40 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
16b50 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
16b60 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
16b70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
16b80 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
16b90 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
16ba0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
16bb0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
16bc0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
16bd0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
16be0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
16bf0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
16c00 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
16c10 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
16c20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
16c30 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
16c40 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
16c50 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
16c60 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
16c70 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
16c80 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
16c90 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
16ca0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
16cb0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
16cc0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
16cd0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
16ce0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
16cf0 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
16d00 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
16d10 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
16d20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
16d30 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
16d40 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
16d50 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
16d60 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
16d70 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
16d80 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
16d90 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
16da0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
16db0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
16dc0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
16dd0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
16de0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
16df0 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
16e00 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
16e10 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
16e20 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
16e30 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
16e40 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
16e50 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
16e60 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
16e70 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
16e80 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
16e90 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
16ea0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
16eb0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
16ec0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
16ed0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
16ee0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
16ef0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
16f00 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
16f10 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
16f20 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
16f30 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
16f40 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
16f50 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
16f60 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
16f70 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
16f80 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
16f90 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
16fa0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
16fb0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
16fc0 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
16fd0 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
16fe0 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
16ff0 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
17000 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
17010 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
17020 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
17030 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
17040 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
17050 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
17060 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17070 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
17080 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
17090 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
170a0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
170b0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
170c0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
170d0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
170e0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
170f0 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
17100 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17110 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
17120 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
17130 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
17140 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17150 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
17160 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17170 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
17180 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
17190 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
171a0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
171b0 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
171c0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
171d0 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
171e0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
171f0 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
17200 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
17210 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
17220 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
17230 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
17240 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
17250 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
17260 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
17270 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
17280 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
17290 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
172a0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
172b0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
172c0 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
172d0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
172e0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
172f0 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
17300 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
17310 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
17320 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
17330 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
17340 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
17350 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
17360 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
17370 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
17380 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17390 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c  NFIG_PCACHE2]] <
173a0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
173b0 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  _PCACHE2</dt>.**
173c0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
173d0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
173e0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
173f0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
17400 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33  o.** an [sqlite3
17410 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
17420 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
17430 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
17440 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
17450 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
17460 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
17470 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c  ntation.)^  ^SQL
17480 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
17490 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
174a0 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
174b0 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
174c0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
174d0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
174e0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
174f0 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
17500 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
17510 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
17520 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
17530 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17540 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
17550 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
17560 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
17570 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
17580 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
17590 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72  opies of the cur
175a0 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63  rent.** page cac
175b0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
175c0 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
175d0 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
175e0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
175f0 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
17600 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
17610 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
17620 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
17630 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
17640 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
17650 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
17660 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
17670 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
17680 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
17690 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
176a0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
176b0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
176c0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
176d0 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
176e0 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
176f0 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
17700 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
17710 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
17720 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
17730 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
17740 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
17750 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
17760 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
17770 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
17780 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
17790 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
177a0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
177b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
177c0 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
177d0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
177e0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
177f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
17800 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
17810 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
17820 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
17830 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
17840 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
17850 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
17860 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
17870 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
17880 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
17890 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
178a0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
178b0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
178c0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
178d0 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
178e0 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
178f0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
17900 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
17910 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
17920 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
17930 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
17940 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
17950 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
17960 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
17970 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
17980 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
17990 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
179a0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
179b0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
179c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
179d0 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
179e0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
179f0 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
17a00 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
17a10 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
17a20 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
17a30 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
17a40 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
17a50 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
17a60 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
17a70 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
17a80 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
17a90 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f  I.** <dd> This o
17aa0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
17ab0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
17ac0 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f   type int. If no
17ad0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20  n-zero, then.** 
17ae0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
17af0 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
17b00 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
17b10 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  er is zero, then
17b20 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a   URI handling.**
17b30 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
17b40 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61  abled. If URI ha
17b50 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
17b60 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ly enabled, all 
17b70 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73  filenames.** pas
17b80 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
17b90 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
17ba0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73  3_open_v2()], [s
17bb0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
17bc0 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
17bd0 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
17be0 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
17bf0 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
17c00 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
17c10 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
17c20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
17c30 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
17c40 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
17c50 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
17c60 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
17c70 65 64 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f  ed. If it is glo
17c80 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
17c90 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
17ca0 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
17cb0 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
17cc0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
17cd0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
17ce0 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
17cf0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
17d00 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75  opened. By defau
17d10 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
17d20 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
17d30 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
17d40 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
17d50 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
17d60 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
17d70 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
17d80 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
17d90 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ned..**.** [[SQL
17da0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
17db0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
17dc0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
17dd0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
17de0 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 20 54  X_SCAN.** <dd> T
17df0 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 73 20  his option taks 
17e00 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72  a single integer
17e10 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
17e20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
17e30 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69  s.** a boolean i
17e40 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c  n order to enabl
17e50 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65  e or disable the
17e60 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67   use of covering
17e70 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20   indices for.** 
17e80 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73  full table scans
17e90 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70   in the query op
17ea0 74 69 6d 69 7a 65 72 2e 20 20 54 68 65 20 64 65  timizer.  The de
17eb0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73  fault setting is
17ec0 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62   determined.** b
17ed0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c  y the [SQLITE_AL
17ee0 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  LOW_COVERING_IND
17ef0 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65  EX_SCAN] compile
17f00 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72  -time option, or
17f10 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74   is "on".** if t
17f20 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  hat compile-time
17f30 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74   option is omitt
17f40 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69  ed..** The abili
17f50 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  ty to disable th
17f60 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
17f70 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
17f80 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a  ll table scans.*
17f90 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d  * is because som
17fa0 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f  e incorrectly co
17fb0 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69  ded legacy appli
17fc0 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61  cations might ma
17fd0 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 61 6c  lfunction.** mal
17fe0 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20 74 68  function when th
17ff0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69  e optimization i
18000 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76  s enabled.  Prov
18010 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74  iding the abilit
18020 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20  y to.** disable 
18030 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  the optimization
18040 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65   allows the olde
18050 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61  r, buggy applica
18060 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72  tion code to wor
18070 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61  k.** without cha
18080 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65  nge even with ne
18090 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  wer versions of 
180a0 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  SQLite..**.** [[
180b0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
180c0 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f  ACHE]] [[SQLITE_
180d0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
180e0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
180f0 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61  _CONFIG_PCACHE a
18100 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  nd SQLITE_CONFIG
18110 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64  _GETPCACHE.** <d
18120 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73  d> These options
18130 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e   are obsolete an
18140 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  d should not be 
18150 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65  used by new code
18160 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65  ..** They are re
18170 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77  tained for backw
18180 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
18190 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e  ty but are now n
181a0 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  o-ops..** </dl>.
181b0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
181c0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
181d0 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
181e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
181f0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
18200 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
18210 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
18220 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
18230 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
18240 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
18250 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
18260 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
18270 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
18280 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
18290 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
182a0 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
182b0 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
182c0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
182d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
182e0 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
182f0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
18300 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
18310 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
18320 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
18330 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
18340 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
18350 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18360 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
18370 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
18380 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
18390 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
183a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
183b0 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
183c0 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
183d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
183e0 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
183f0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
18400 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
18410 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18420 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
18430 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
18440 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
18450 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
18460 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
18470 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
18480 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
18490 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
184a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
184b0 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
184c0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
184d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
184e0 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
184f0 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65   /* no-op */.#de
18500 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18510 49 47 5f 47 45 54 50 43 41 43 48 45 20 20 20 20  IG_GETPCACHE    
18520 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  15  /* no-op */.
18530 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18540 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20  ONFIG_LOG       
18550 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c     16  /* xFunc,
18560 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e   void* */.#defin
18570 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
18580 55 52 49 20 20 20 20 20 20 20 20 20 20 31 37 20  URI          17 
18590 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69   /* int */.#defi
185a0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
185b0 5f 50 43 41 43 48 45 32 20 20 20 20 20 20 31 38  _PCACHE2      18
185c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
185d0 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
185e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
185f0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
18600 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74  2   19  /* sqlit
18610 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
18620 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  s2* */.#define S
18630 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
18640 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
18650 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 0a   20  /* int */..
18660 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
18670 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
18680 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
18690 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
186a0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
186b0 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
186c0 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
186d0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
186e0 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
186f0 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
18700 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
18710 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
18720 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
18730 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
18740 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
18750 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
18760 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
18770 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
18780 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
18790 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
187a0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
187b0 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
187c0 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
187d0 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
187e0 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
187f0 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
18800 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
18810 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
18820 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
18830 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
18840 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
18850 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
18860 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
18870 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
18880 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
18890 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
188a0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
188b0 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
188c0 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
188d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
188e0 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
188f0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
18900 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
18910 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
18920 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
18930 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
18940 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
18950 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
18960 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
18970 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
18980 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
18990 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
189a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
189b0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
189c0 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
189d0 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
189e0 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
189f0 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
18a00 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
18a10 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
18a20 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
18a30 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
18a40 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
18a50 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
18a60 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
18a70 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
18a80 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
18a90 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
18aa0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
18ab0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
18ac0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
18ad0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
18ae0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
18af0 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
18b00 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
18b10 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
18b20 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
18b30 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
18b40 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
18b50 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
18b60 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
18b70 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
18b80 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
18b90 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
18ba0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
18bb0 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
18bc0 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
18bd0 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
18be0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
18bf0 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
18c00 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
18c10 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
18c20 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
18c30 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
18c40 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
18c50 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
18c60 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
18c70 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
18c80 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
18c90 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
18ca0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
18cb0 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
18cc0 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
18cd0 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
18ce0 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
18cf0 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
18d00 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
18d10 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
18d20 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
18d30 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
18d40 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
18d50 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
18d60 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
18d70 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
18d80 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
18d90 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
18da0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
18db0 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
18dc0 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
18dd0 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
18de0 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
18df0 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
18e00 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
18e10 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
18e20 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
18e30 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
18e40 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
18e50 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
18e60 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
18e70 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
18e80 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
18e90 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
18ea0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
18eb0 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
18ec0 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
18ed0 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
18ee0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
18ef0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
18f00 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
18f10 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
18f20 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
18f30 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
18f40 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
18f50 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
18f60 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
18f70 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
18f80 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
18f90 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
18fa0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
18fb0 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
18fc0 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
18fd0 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
18fe0 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
18ff0 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
19000 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
19010 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
19020 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
19030 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
19040 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
19050 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
19060 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
19070 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
19080 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
19090 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
190a0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
190b0 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
190c0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
190d0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
190e0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
190f0 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
19100 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
19110 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
19120 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
19130 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
19140 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
19150 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
19160 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
19170 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
19180 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
19190 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
191a0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
191b0 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
191c0 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
191d0 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
191e0 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
191f0 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
19200 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
19210 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
19220 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
19230 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
19240 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
19250 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
19260 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
19270 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
19280 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
19290 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
192a0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
192b0 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
192c0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
192d0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
192e0 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
192f0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
19300 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
19310 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
19320 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
19330 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
19340 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
19350 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
19360 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
19370 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19380 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
19390 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
193a0 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
193b0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
193c0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
193d0 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
193e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
193f0 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
19400 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
19410 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
19420 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
19430 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
19440 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
19450 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
19460 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
19470 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
19480 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
19490 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
194a0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
194b0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
194c0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
194d0 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
194e0 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
194f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
19500 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
19510 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  Rowid.**.** ^Eac
19520 68 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51  h entry in an SQ
19530 4c 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61  Lite table has a
19540 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73   unique 64-bit s
19550 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72  igned.** integer
19560 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20   key called the 
19570 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22  [ROWID | "rowid"
19580 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73  ]. ^The rowid is
19590 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c   always availabl
195a0 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63  e.** as an undec
195b0 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d  lared column nam
195c0 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f  ed ROWID, OID, o
195d0 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e  r _ROWID_ as lon
195e0 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61  g as those.** na
195f0 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f  mes are not also
19600 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69   used by explici
19610 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c  tly declared col
19620 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65  umns. ^If.** the
19630 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c   table has a col
19640 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54  umn of type [INT
19650 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59  EGER PRIMARY KEY
19660 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75  ] then that colu
19670 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72  mn.** is another
19680 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72   alias for the r
19690 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  owid..**.** ^Thi
196a0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
196b0 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  s the [rowid] of
196c0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
196d0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b  .** successful [
196e0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65  INSERT] into the
196f0 20 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74   database from t
19700 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
19710 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74  nection].** in t
19720 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19730 74 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74  t.  ^As of SQLit
19740 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c  e version 3.7.7,
19750 20 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a   this routines.*
19760 2a 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61  * records the la
19770 73 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20  st insert rowid 
19780 6f 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79  of both ordinary
19790 20 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72   tables and [vir
197a0 74 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a  tual tables]..**
197b0 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
197c0 75 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20  ul [INSERT]s.** 
197d0 68 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72  have ever occurr
197e0 65 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62  ed on that datab
197f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
19800 7a 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64  zero is returned
19810 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20  ..**.** ^(If an 
19820 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20  [INSERT] occurs 
19830 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72  within a trigger
19840 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69   or within a [vi
19850 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20  rtual table].** 
19860 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69  method, then thi
19870 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72  s routine will r
19880 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64  eturn the [rowid
19890 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65  ] of the inserte
198a0 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67  d.** row as long
198b0 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20   as the trigger 
198c0 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  or virtual table
198d0 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69   method is runni
198e0 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20  ng..** But once 
198f0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
19900 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
19910 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61  hod ends, the va
19920 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a  lue returned .**
19930 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65   by this routine
19940 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74   reverts to what
19950 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74   it was before t
19960 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
19970 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d  rtual.** table m
19980 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a  ethod began.)^.*
19990 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54  *.** ^An [INSERT
199a0 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65  ] that fails due
199b0 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74   to a constraint
199c0 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f   violation is no
199d0 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  t a.** successfu
199e0 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64  l [INSERT] and d
199f0 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74  oes not change t
19a00 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
19a10 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75  d by this.** rou
19a20 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53  tine.  ^Thus INS
19a30 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53  ERT OR FAIL, INS
19a40 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49  ERT OR IGNORE, I
19a50 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43  NSERT OR ROLLBAC
19a60 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54  K,.** and INSERT
19a70 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e   OR ABORT make n
19a80 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65  o changes to the
19a90 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
19aa0 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
19ab0 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65   when their inse
19ac0 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28  rtion fails.  ^(
19ad0 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52  When INSERT OR R
19ae0 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e  EPLACE.** encoun
19af0 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e  ters a constrain
19b00 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20  t violation, it 
19b10 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20  does not fail.  
19b20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f  The.** INSERT co
19b30 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c  ntinues to compl
19b40 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65  etion after dele
19b50 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63  ting rows that c
19b60 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e  aused.** the con
19b70 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20  straint problem 
19b80 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50  so INSERT OR REP
19b90 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73  LACE will always
19ba0 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72   change.** the r
19bb0 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74  eturn value of t
19bc0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e  his interface.)^
19bd0 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20  .**.** ^For the 
19be0 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73  purposes of this
19bf0 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e   routine, an [IN
19c00 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65  SERT] is conside
19c10 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63  red to.** be suc
19c20 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20  cessful even if 
19c30 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74  it is subsequent
19c40 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a  ly rolled back..
19c50 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  **.** This funct
19c60 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c  ion is accessibl
19c70 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  e to SQL stateme
19c80 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b  nts via the.** [
19c90 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
19ca0 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  d() SQL function
19cb0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
19cc0 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65  parate thread pe
19cd0 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e  rforms a new [IN
19ce0 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d  SERT] on the sam
19cf0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  e.** database co
19d00 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74  nnection while t
19d10 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74  he [sqlite3_last
19d20 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d  _insert_rowid()]
19d30 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
19d40 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73  running and thus
19d50 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73   changes the las
19d60 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d  t insert [rowid]
19d70 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61  ,.** then the va
19d80 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
19d90 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e  [sqlite3_last_in
19da0 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73  sert_rowid()] is
19db0 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c  .** unpredictabl
19dc0 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20  e and might not 
19dd0 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65  equal either the
19de0 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a   old or the new.
19df0 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  ** last insert [
19e00 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 53 51 4c 49 54  rowid]..*/.SQLIT
19e10 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
19e20 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
19e30 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
19e40 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
19e50 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
19e60 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
19e70 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
19e80 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
19e90 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
19ea0 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
19eb0 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
19ec0 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
19ed0 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
19ee0 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
19ef0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
19f00 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
19f10 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
19f20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
19f30 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
19f40 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
19f50 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65  ** ^(Only change
19f60 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
19f70 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
19f80 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
19f90 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
19fa0 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
19fb0 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
19fc0 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
19fd0 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
19fe0 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65  riggers or [fore
19ff0 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
1a000 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1a010 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  .)^ Use the.** [
1a020 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
1a030 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
1a040 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
1a050 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
1a060 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
1a070 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
1a080 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
1a090 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
1a0a0 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68  tions..**.** ^Ch
1a0b0 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
1a0c0 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74  that are simulat
1a0d0 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41  ed by an [INSTEA
1a0e0 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a  D OF trigger].**
1a0f0 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
1a100 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62  .  Only real tab
1a110 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  le changes are c
1a120 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ounted..**.** ^(
1a130 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
1a140 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
1a150 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
1a160 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
1a170 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
1a180 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
1a190 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
1a1a0 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
1a1b0 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
1a1c0 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
1a1d0 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
1a1e0 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
1a1f0 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
1a200 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
1a210 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
1a220 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
1a230 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
1a240 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
1a250 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e  t row changes.)^
1a260 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
1a270 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
1a280 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
1a290 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
1a2a0 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
1a2b0 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
1a2c0 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
1a2d0 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
1a2e0 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
1a2f0 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
1a300 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
1a310 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
1a320 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
1a330 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
1a340 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
1a350 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
1a360 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
1a370 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
1a380 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
1a390 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
1a3a0 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
1a3b0 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
1a3c0 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
1a3d0 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
1a3e0 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
1a3f0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  n..**.** ^Callin
1a400 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
1a410 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
1a420 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
1a430 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
1a440 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
1a450 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
1a460 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1a470 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
1a480 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
1a490 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
1a4a0 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
1a4b0 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
1a4c0 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
1a4d0 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
1a4e0 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
1a4f0 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
1a500 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
1a510 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
1a520 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
1a530 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
1a540 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
1a550 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
1a560 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
1a570 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
1a580 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
1a590 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
1a5a0 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74  op level.  ^(Wit
1a5b0 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
1a5c0 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
1a5d0 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
1a5e0 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
1a5f0 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
1a600 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
1a610 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
1a620 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
1a630 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
1a640 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
1a650 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
1a660 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
1a670 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
1a680 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
1a690 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
1a6a0 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
1a6b0 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
1a6c0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
1a6d0 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
1a6e0 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
1a6f0 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a   own context.)^.
1a700 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
1a710 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
1a720 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
1a730 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
1a740 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
1a750 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
1a760 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1a770 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1a780 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1a790 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1a7a0 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1a7b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1a7c0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1a7d0 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
1a7e0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
1a7f0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1a800 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
1a810 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
1a820 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  aningful..*/.SQL
1a830 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1a840 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  te3_changes(sqli
1a850 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1a860 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75  PI3REF: Total Nu
1a870 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
1a880 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
1a890 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
1a8a0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
1a8b0 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75   row changes cau
1a8c0 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c  sed by [INSERT],
1a8d0 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20  .** [UPDATE] or 
1a8e0 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
1a8f0 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64  nts since the [d
1a900 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1a910 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a  on] was opened..
1a920 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72  ** ^(The count r
1a930 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
1a940 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
1a950 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20  () includes all 
1a960 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20  changes.** from 
1a970 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47  all [CREATE TRIG
1a980 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63  GER | trigger] c
1a990 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e  ontexts and chan
1a9a0 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b  ges made by.** [
1a9b0 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
1a9c0 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a  ons]. However,.*
1a9d0 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73  * the count does
1a9e0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
1a9f0 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70  nges used to imp
1aa00 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d  lement [REPLACE]
1aa10 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a   constraints,.**
1aa20 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72   do rollbacks or
1aa30 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
1aa40 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c  g, or [DROP TABL
1aa50 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20  E] processing.  
1aa60 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65  The.** count doe
1aa70 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f  s not include ro
1aa80 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74  ws of views that
1aa90 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41   fire an [INSTEA
1aaa0 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a  D OF trigger],.*
1aab0 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20  * though if the 
1aac0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1aad0 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  er makes changes
1aae0 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f   of its own, tho
1aaf0 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61  se changes .** a
1ab00 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a  re counted.)^.**
1ab10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f   ^The sqlite3_to
1ab20 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75  tal_changes() fu
1ab30 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68  nction counts th
1ab40 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f  e changes as soo
1ab50 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74  n as.** the stat
1ab60 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73  ement that makes
1ab70 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74   them is complet
1ab80 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61  ed (when the sta
1ab90 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a  tement handle.**
1aba0 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73   is passed to [s
1abb0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
1abc0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
1abd0 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20  lize()])..**.** 
1abe0 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
1abf0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d  lite3_changes()]
1ac00 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
1ac10 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
1ac20 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
1ac30 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65  he [total_change
1ac40 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
1ac50 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
1ac60 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
1ac70 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
1ac80 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
1ac90 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
1aca0 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f  hile [sqlite3_to
1acb0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  tal_changes()] i
1acc0 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
1acd0 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
1ace0 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63  rned is unpredic
1acf0 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
1ad00 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 53 51 4c  aningful..*/.SQL
1ad10 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1ad20 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1ad30 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1ad40 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
1ad50 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
1ad60 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
1ad70 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
1ad80 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
1ad90 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
1ada0 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
1adb0 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
1adc0 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
1add0 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
1ade0 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
1adf0 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
1ae00 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
1ae10 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
1ae20 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
1ae30 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
1ae40 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
1ae50 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
1ae60 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
1ae70 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
1ae80 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
1ae90 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
1aea0 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
1aeb0 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
1aec0 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
1aed0 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
1aee0 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
1aef0 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
1af00 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
1af10 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
1af20 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
1af30 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
1af40 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1af50 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
1af60 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
1af70 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
1af80 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1af90 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
1afa0 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
1afb0 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
1afc0 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
1afd0 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
1afe0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
1aff0 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
1b000 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
1b010 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
1b020 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
1b030 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
1b040 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
1b050 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
1b060 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
1b070 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
1b080 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
1b090 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
1b0a0 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
1b0b0 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
1b0c0 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
1b0d0 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
1b0e0 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
1b0f0 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
1b100 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
1b110 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
1b120 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
1b130 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
1b140 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
1b150 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
1b160 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
1b170 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
1b180 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
1b190 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
1b1a0 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
1b1b0 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
1b1c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1b1d0 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
1b1e0 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
1b1f0 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
1b200 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
1b210 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
1b220 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
1b230 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
1b240 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
1b250 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
1b260 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
1b270 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
1b280 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
1b290 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
1b2a0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b2b0 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
1b2c0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1b2d0 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
1b2e0 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
1b2f0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
1b300 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
1b310 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
1b320 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
1b330 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
1b340 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
1b350 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1b360 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
1b370 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
1b380 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
1b390 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
1b3a0 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
1b3b0 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
1b3c0 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
1b3d0 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
1b3e0 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
1b3f0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
1b400 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
1b410 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1b420 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
1b430 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
1b440 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
1b450 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
1b460 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
1b470 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
1b480 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
1b490 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
1b4a0 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
1b4b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1b4c0 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
1b4d0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
1b4e0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
1b4f0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b500 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
1b510 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
1b520 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
1b530 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
1b540 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
1b550 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
1b560 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
1b570 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
1b580 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
1b590 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
1b5a0 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
1b5b0 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
1b5c0 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
1b5d0 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
1b5e0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
1b5f0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
1b600 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
1b610 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
1b620 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
1b630 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
1b640 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
1b650 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
1b660 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
1b670 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
1b680 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
1b690 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
1b6a0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
1b6b0 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
1b6c0 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
1b6d0 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
1b6e0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
1b6f0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
1b700 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
1b710 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
1b720 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
1b730 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
1b740 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
1b750 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
1b760 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
1b770 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
1b780 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
1b790 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
1b7a0 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
1b7b0 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
1b7c0 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
1b7d0 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
1b7e0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
1b7f0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
1b800 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
1b810 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
1b820 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
1b830 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
1b840 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
1b850 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
1b860 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
1b870 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
1b880 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
1b890 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
1b8a0 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
1b8b0 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
1b8c0 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
1b8d0 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
1b8e0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
1b8f0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
1b900 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
1b910 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
1b920 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
1b930 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
1b940 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
1b950 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
1b960 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
1b970 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
1b980 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
1b990 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
1b9a0 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
1b9b0 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
1b9c0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
1b9d0 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
1b9e0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
1b9f0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
1ba00 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
1ba10 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
1ba20 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
1ba30 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
1ba40 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
1ba50 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
1ba60 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
1ba70 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1ba80 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
1ba90 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
1baa0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
1bab0 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
1bac0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
1bad0 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
1bae0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
1baf0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 53 51 4c  te order..*/.SQL
1bb00 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
1bb10 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
1bb20 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 53  st char *sql);.S
1bb30 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1bb40 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1bb50 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  (const void *sql
1bb60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1bb70 45 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43  EF: Register A C
1bb80 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c  allback To Handl
1bb90 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72  e SQLITE_BUSY Er
1bba0 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  rors.**.** ^This
1bbb0 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20   routine sets a 
1bbc0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1bbd0 6e 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20  n that might be 
1bbe0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72  invoked whenever
1bbf0 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69  .** an attempt i
1bc00 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 61  s made to open a
1bc10 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 20   database table 
1bc20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 74 68 72  that another thr
1bc30 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73  ead.** or proces
1bc40 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a  s has locked..**
1bc50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62 75 73 79  .** ^If the busy
1bc60 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c   callback is NUL
1bc70 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  L, then [SQLITE_
1bc80 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
1bc90 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a  _IOERR_BLOCKED].
1bca0 2a 2a 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  ** is returned i
1bcb0 6d 6d 65 64 69 61 74 65 6c 79 20 75 70 6f 6e 20  mmediately upon 
1bcc0 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20 74 68 65  encountering the
1bcd0 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74 68 65 20   lock.  ^If the 
1bce0 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  busy callback.**
1bcf0 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68   is not NULL, th
1bd00 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1bd10 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
1bd20 20 77 69 74 68 20 74 77 6f 20 61 72 67 75 6d 65   with two argume
1bd30 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
1bd40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
1bd50 6f 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  o the busy handl
1bd60 65 72 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  er is a copy of 
1bd70 74 68 65 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65  the void* pointe
1bd80 72 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 74 68  r which.** is th
1bd90 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
1bda0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 75 73 79   to sqlite3_busy
1bdb0 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68  _handler().  ^Th
1bdc0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
1bdd0 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79  t to.** the busy
1bde0 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63   handler callbac
1bdf0 6b 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  k is the number 
1be00 6f 66 20 74 69 6d 65 73 20 74 68 61 74 20 74 68  of times that th
1be10 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 68  e busy handler h
1be20 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b  as.** been invok
1be30 65 64 20 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b  ed for this lock
1be40 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
1be50 74 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c  the.** busy call
1be60 62 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20  back returns 0, 
1be70 74 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e  then no addition
1be80 61 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20  al attempts are 
1be90 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73  made to.** acces
1bea0 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61  s the database a
1beb0 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  nd [SQLITE_BUSY]
1bec0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
1bed0 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65  R_BLOCKED] is re
1bee0 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  turned..** ^If t
1bef0 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1bf00 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
1bf10 65 6e 20 61 6e 6f 74 68 65 72 20 61 74 74 65 6d  en another attem
1bf20 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f  pt.** is made to
1bf30 20 6f 70 65 6e 20 74 68 65 20 64 61 74 61 62 61   open the databa
1bf40 73 65 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61  se for reading a
1bf50 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65 70  nd the cycle rep
1bf60 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  eats..**.** The 
1bf70 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62 75  presence of a bu
1bf80 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73 20  sy handler does 
1bf90 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74 68  not guarantee th
1bfa0 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69 6e  at it will be in
1bfb0 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68  voked.** when th
1bfc0 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74  ere is lock cont
1bfd0 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69  ention. ^If SQLi
1bfe0 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68  te determines th
1bff0 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  at invoking the 
1c000 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  busy.** handler 
1c010 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  could result in 
1c020 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77  a deadlock, it w
1c030 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e 64  ill go ahead and
1c040 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
1c050 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c  BUSY].** or [SQL
1c060 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
1c070 44 5d 20 69 6e 73 74 65 61 64 20 6f 66 20 69 6e  D] instead of in
1c080 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 20  voking the busy 
1c090 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73  handler..** Cons
1c0a0 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20  ider a scenario 
1c0b0 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73  where one proces
1c0c0 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
1c0d0 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a  ead lock that.**
1c0e0 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f   it is trying to
1c0f0 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65   promote to a re
1c100 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a  served lock and.
1c110 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63  ** a second proc
1c120 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ess is holding a
1c130 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74   reserved lock t
1c140 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e 67  hat it is trying
1c150 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
1c160 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c  o an exclusive l
1c170 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20  ock.  The first 
1c180 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70  process cannot p
1c190 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73  roceed.** becaus
1c1a0 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
1c1b0 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e  by the second an
1c1c0 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f  d the second pro
1c1d0 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70  cess cannot.** p
1c1e0 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20 69  roceed because i
1c1f0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
1c200 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20 62  the first.  If b
1c210 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a  oth processes.**
1c220 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79   invoke the busy
1c230 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68   handlers, neith
1c240 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79  er will make any
1c250 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72   progress.  Ther
1c260 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65  efore,.** SQLite
1c270 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
1c280 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66  _BUSY] for the f
1c290 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f  irst process, ho
1c2a0 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a  ping that this.*
1c2b0 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68  * will induce th
1c2c0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 20  e first process 
1c2d0 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20 72  to release its r
1c2e0 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c  ead lock and all
1c2f0 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64  ow.** the second
1c300 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63   process to proc
1c310 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
1c320 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c  default busy cal
1c330 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a  lback is NULL..*
1c340 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
1c350 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69 73  E_BUSY] error is
1c360 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b 53   converted to [S
1c370 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
1c380 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  KED].** when SQL
1c390 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d 69  ite is in the mi
1c3a0 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65 20  ddle of a large 
1c3b0 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65 72  transaction wher
1c3c0 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61  e all the.** cha
1c3d0 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69  nges will not fi
1c3e0 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65  t into the in-me
1c3f0 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51 4c  mory cache.  SQL
1c400 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65  ite will.** alre
1c410 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45 52  ady hold a RESER
1c420 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  VED lock on the 
1c430 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 62  database file, b
1c440 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74  ut it needs.** t
1c450 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c  o promote this l
1c460 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56 45  ock to EXCLUSIVE
1c470 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e 20   so that it can 
1c480 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70  spill cache.** p
1c490 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64 61  ages into the da
1c4a0 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74 68  tabase file with
1c4b0 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63  out harm to conc
1c4c0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72  urrent.** reader
1c4d0 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75 6e  s.  ^If it is un
1c4e0 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20  able to promote 
1c4f0 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74  the lock, then t
1c500 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20  he in-memory.** 
1c510 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c 65  cache will be le
1c520 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69  ft in an inconsi
1c530 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64 20  stent state and 
1c540 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  so the error.** 
1c550 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65 64  code is promoted
1c560 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74 69   from the relati
1c570 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c  vely benign [SQL
1c580 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20  ITE_BUSY] to.** 
1c590 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65 20  the more severe 
1c5a0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
1c5b0 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20 65  OCKED].  ^This e
1c5c0 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74  rror code promot
1c5d0 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e  ion.** forces an
1c5e0 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62   automatic rollb
1c5f0 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e 67  ack of the chang
1c600 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20  es.  See the.** 
1c610 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72 61  <a href="/cvstra
1c620 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74  c/wiki?p=Corrupt
1c630 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79  ionFollowingBusy
1c640 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75  Error">.** Corru
1c650 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75  ptionFollowingBu
1c660 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69  syError</a> wiki
1c670 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73 63   page for a disc
1c680 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a  ussion of why.**
1c690 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74 61   this is importa
1c6a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  nt..**.** ^(Ther
1c6b0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
1c6c0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
1c6d0 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72 20  ler defined for 
1c6e0 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73  each.** [databas
1c6f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20  e connection].  
1c700 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62 75  Setting a new bu
1c710 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61 72  sy handler clear
1c720 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75  s any.** previou
1c730 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72 2e  sly set handler.
1c740 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 63  )^  ^Note that c
1c750 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
1c760 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a  busy_timeout()].
1c770 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74  ** will also set
1c780 20 6f 72 20 63 6c 65 61 72 20 74 68 65 20 62 75   or clear the bu
1c790 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a  sy handler..**.*
1c7a0 2a 20 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62  * The busy callb
1c7b0 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74  ack should not t
1c7c0 61 6b 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20  ake any actions 
1c7d0 77 68 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65  which modify the
1c7e0 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1c7f0 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76  nection that inv
1c800 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1c810 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73 75 63 68  ndler.  Any such
1c820 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75   actions.** resu
1c830 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  lt in undefined 
1c840 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a  behavior..** .**
1c850 20 41 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   A busy handler 
1c860 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74  must not close t
1c870 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1c880 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72  ection.** or [pr
1c890 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1c8a0 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  ] that invoked t
1c8b0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
1c8c0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69  .*/.SQLITE_API i
1c8d0 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  nt sqlite3_busy_
1c8e0 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a  handler(sqlite3*
1c8f0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69  , int(*)(void*,i
1c900 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  nt), void*);../*
1c910 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
1c920 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74  t A Busy Timeout
1c930 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
1c940 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c  tine sets a [sql
1c950 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
1c960 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72  r | busy handler
1c970 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a  ] that sleeps.**
1c980 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 65 64   for a specified
1c990 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20   amount of time 
1c9a0 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20  when a table is 
1c9b0 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61  locked.  ^The ha
1c9c0 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c  ndler.** will sl
1c9d0 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d  eep multiple tim
1c9e0 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73  es until at leas
1c9f0 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f  t "ms" milliseco
1ca00 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a  nds of sleeping.
1ca10 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61  ** have accumula
1ca20 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20  ted.  ^After at 
1ca30 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69  least "ms" milli
1ca40 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70  seconds of sleep
1ca50 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64  ing,.** the hand
1ca60 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20 77 68  ler returns 0 wh
1ca70 69 63 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69  ich causes [sqli
1ca80 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72  te3_step()] to r
1ca90 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45  eturn.** [SQLITE
1caa0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
1cab0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
1cac0 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  ..**.** ^Calling
1cad0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1cae0 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c  th an argument l
1caf0 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61  ess than or equa
1cb00 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72  l to zero.** tur
1cb10 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20  ns off all busy 
1cb20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  handlers..**.** 
1cb30 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1cb40 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1cb50 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20  y handler for a 
1cb60 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64  particular.** [d
1cb70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1cb80 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65  on] any any give
1cb90 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e  n moment.  If an
1cba0 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c  other busy handl
1cbb0 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65  er.** was define
1cbc0 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74  d  (using [sqlit
1cbd0 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
1cbe0 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c  )]) prior to cal
1cbf0 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75  ling.** this rou
1cc00 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72  tine, that other
1cc10 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
1cc20 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 53   cleared.)^.*/.S
1cc30 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1cc40 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1cc50 75 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  ut(sqlite3*, int
1cc60 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   ms);../*.** CAP
1cc70 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e  I3REF: Convenien
1cc80 63 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20  ce Routines For 
1cc90 52 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a  Running Queries.
1cca0 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20  **.** This is a 
1ccb0 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
1ccc0 20 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76   that is preserv
1ccd0 65 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ed for backwards
1cce0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
1ccf0 2a 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69  ** Use of this i
1cd00 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
1cd10 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a  recommended..**.
1cd20 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41  ** Definition: A
1cd30 20 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65   <b>result table
1cd40 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64  </b> is memory d
1cd50 61 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72  ata structure cr
1cd60 65 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  eated by the.** 
1cd70 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62  [sqlite3_get_tab
1cd80 6c 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  le()] interface.
1cd90 20 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65    A result table
1cda0 20 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20   records the.** 
1cdb0 63 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72  complete query r
1cdc0 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20  esults from one 
1cdd0 6f 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e  or more queries.
1cde0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
1cdf0 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61   conceptually ha
1ce00 73 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f  s a number of ro
1ce10 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20  ws and columns. 
1ce20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75   But.** these nu
1ce30 6d 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61  mbers are not pa
1ce40 72 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  rt of the result
1ce50 20 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20   table itself.  
1ce60 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73  These.** numbers
1ce70 20 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65   are obtained se
1ce80 70 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e  parately.  Let N
1ce90 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   be the number o
1cea0 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20  f rows.** and M 
1ceb0 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
1cec0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20   columns..**.** 
1ced0 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69  A result table i
1cee0 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
1cef0 69 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74  inters to zero-t
1cf00 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20  erminated UTF-8 
1cf10 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72  strings..** Ther
1cf20 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c  e are (N+1)*M el
1cf30 65 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72  ements in the ar
1cf40 72 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20  ray.  The first 
1cf50 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74  M pointers point
1cf60 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  .** to zero-term
1cf70 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74  inated strings t
1cf80 68 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65  hat  contain the
1cf90 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f   names of the co
1cfa0 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65  lumns..** The re
1cfb0 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20  maining entries 
1cfc0 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65  all point to que
1cfd0 72 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c  ry results.  NUL
1cfe0 4c 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a  L values result.
1cff0 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74  ** in NULL point
1d000 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20  ers.  All other 
1d010 76 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68  values are in th
1d020 65 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74  eir UTF-8 zero-t
1d030 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72  erminated.** str
1d040 69 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69  ing representati
1d050 6f 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62  on as returned b
1d060 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  y [sqlite3_colum
1d070 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a  n_text()]..**.**
1d080 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1d090 6d 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66  might consist of
1d0a0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d   one or more mem
1d0b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
1d0c0 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61  .** It is not sa
1d0d0 66 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73  fe to pass a res
1d0e0 75 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74  ult table direct
1d0f0 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  ly to [sqlite3_f
1d100 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73  ree()]..** A res
1d110 75 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64  ult table should
1d120 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20   be deallocated 
1d130 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
1d140 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a  ree_table()]..**
1d150 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d  .** ^(As an exam
1d160 70 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ple of the resul
1d170 74 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20  t table format, 
1d180 73 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20  suppose a query 
1d190 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20  result.** is as 
1d1a0 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
1d1b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1d1c0 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20  .**        Name 
1d1d0 20 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20         | Age.** 
1d1e0 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d         ---------
1d1f0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a  --------------.*
1d200 2a 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20  *        Alice  
1d210 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20       | 43.**    
1d220 20 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20      Bob         
1d230 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43  | 28.**        C
1d240 69 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a  indy       | 21.
1d250 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
1d260 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65  quote>.**.** The
1d270 72 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d  re are two colum
1d280 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72  n (M==2) and thr
1d290 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20  ee rows (N==3). 
1d2a0 20 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73   Thus the.** res
1d2b0 75 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20  ult table has 8 
1d2c0 65 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73  entries.  Suppos
1d2d0 65 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62  e the result tab
1d2e0 6c 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20  le is stored.** 
1d2f0 69 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65  in an array name
1d300 73 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65  s azResult.  The
1d310 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73  n azResult holds
1d320 20 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a   this content:.*
1d330 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1d340 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1d350 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d   azResult&#91;0]
1d360 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20   = "Name";.**   
1d370 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1d380 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a  1;1] = "Age";.**
1d390 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1d3a0 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65  &#91;2] = "Alice
1d3b0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1d3c0 65 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22  esult&#91;3] = "
1d3d0 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  43";.**        a
1d3e0 7a 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d  zResult&#91;4] =
1d3f0 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20   "Bob";.**      
1d400 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35    azResult&#91;5
1d410 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20  ] = "28";.**    
1d420 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
1d430 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a  ;6] = "Cindy";.*
1d440 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1d450 74 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b  t&#91;7] = "21";
1d460 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1d470 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20  kquote>)^.**.** 
1d480 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74  ^The sqlite3_get
1d490 5f 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f  _table() functio
1d4a0 6e 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20  n evaluates one 
1d4b0 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63  or more.** semic
1d4c0 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53  olon-separated S
1d4d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e  QL statements in
1d4e0 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e   the zero-termin
1d4f0 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74  ated UTF-8.** st
1d500 72 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20  ring of its 2nd 
1d510 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
1d520 74 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74  turns a result t
1d530 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70  able to the.** p
1d540 6f 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20  ointer given in 
1d550 69 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65  its 3rd paramete
1d560 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74  r..**.** After t
1d570 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68  he application h
1d580 61 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68  as finished with
1d590 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
1d5a0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1d5b0 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74  le(),.** it must
1d5c0 20 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74   pass the result
1d5d0 20 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74   table pointer t
1d5e0 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  o sqlite3_free_t
1d5f0 61 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20  able() in order 
1d600 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68  to.** release th
1d610 65 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61  e memory that wa
1d620 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63  s malloced.  Bec
1d630 61 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20  ause of the way 
1d640 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
1d650 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e  malloc()] happen
1d660 73 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33  s within sqlite3
1d670 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68  _get_table(), th
1d680 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e  e calling.** fun
1d690 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74  ction must not t
1d6a0 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69  ry to call [sqli
1d6b0 74 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65  te3_free()] dire
1d6c0 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b  ctly.  Only.** [
1d6d0 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62  sqlite3_free_tab
1d6e0 6c 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f  le()] is able to
1d6f0 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d   release the mem
1d700 6f 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64  ory properly and
1d710 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54   safely..**.** T
1d720 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  he sqlite3_get_t
1d730 61 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  able() interface
1d740 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   is implemented 
1d750 61 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f  as a wrapper aro
1d760 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  und.** [sqlite3_
1d770 65 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71  exec()].  The sq
1d780 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1d790 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e  ) routine does n
1d7a0 6f 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a  ot have access.*
1d7b0 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61  * to any interna
1d7c0 6c 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  l data structure
1d7d0 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74  s of SQLite.  It
1d7e0 20 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70   uses only the p
1d7f0 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61  ublic.** interfa
1d800 63 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e  ce defined here.
1d810 20 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e    As a consequen
1d820 63 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20  ce, errors that 
1d830 6f 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20  occur in the.** 
1d840 77 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75  wrapper layer ou
1d850 74 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74  tside of the int
1d860 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65  ernal [sqlite3_e
1d870 78 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20  xec()] call are 
1d880 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64  not.** reflected
1d890 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
1d8a0 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
1d8b0 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a  _errcode()] or.*
1d8c0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
1d8d0 67 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  g()]..*/.SQLITE_
1d8e0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
1d8f0 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73 71 6c  get_table(.  sql
1d900 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
1d910 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20 64 61     /* An open da
1d920 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f 6e 73  tabase */.  cons
1d930 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
1d940 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65    /* SQL to be e
1d950 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 63 68  valuated */.  ch
1d960 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c 74 2c  ar ***pazResult,
1d970 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73 20 6f      /* Results o
1d980 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f 0a 20  f the query */. 
1d990 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20 20 20   int *pnRow,    
1d9a0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
1d9b0 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77 73 20   of result rows 
1d9c0 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
1d9d0 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c    int *pnColumn,
1d9e0 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65          /* Numbe
1d9f0 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f 6c 75  r of result colu
1da00 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  mns written here
1da10 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70 7a 45   */.  char **pzE
1da20 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a 20 45  rrmsg       /* E
1da30 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e  rror msg written
1da40 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49   here */.);.SQLI
1da50 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
1da60 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1da70 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1da80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1da90 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1daa0 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1dab0 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1dac0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1dad0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1dae0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1daf0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1db00 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1db10 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1db20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1db30 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1db40 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1db50 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1db60 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1db70 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1db80 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1db90 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1dba0 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1dbb0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1dbc0 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1dbd0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1dbe0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1dbf0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1dc00 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1dc10 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1dc20 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1dc30 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1dc40 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1dc50 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1dc60 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1dc70 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1dc80 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1dc90 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1dca0 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1dcb0 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1dcc0 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1dcd0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1dce0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1dcf0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1dd00 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1dd10 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1dd20 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1dd30 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1dd40 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1dd50 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1dd60 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1dd70 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1dd80 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1dd90 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1dda0 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1ddb0 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1ddc0 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1ddd0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1dde0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1ddf0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1de00 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1de10 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1de20 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1de30 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1de40 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1de50 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1de60 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1de70 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1de80 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1de90 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1dea0 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1deb0 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1dec0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1ded0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1dee0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1def0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1df00 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1df10 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1df20 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1df30 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1df40 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1df50 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1df60 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1df70 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1df80 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1df90 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1dfa0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1dfb0 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1dfc0 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1dfd0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1dfe0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1dff0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1e000 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1e010 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1e020 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1e030 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1e040 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1e050 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1e060 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1e070 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1e080 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1e090 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1e0a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1e0b0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1e0c0 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1e0d0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1e0e0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1e0f0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1e100 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1e110 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1e120 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1e130 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1e140 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1e150 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1e160 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1e170 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1e180 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1e190 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1e1a0 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1e1b0 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1e1c0 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1e1d0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1e1e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1e1f0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1e200 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1e210 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1e220 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1e230 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1e240 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1e250 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1e260 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1e270 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1e280 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1e290 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1e2a0 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1e2b0 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1e2c0 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1e2d0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1e2e0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1e2f0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1e300 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1e310 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1e320 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1e330 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1e340 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1e350 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1e360 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1e370 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1e380 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1e390 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1e3a0 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1e3b0 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1e3c0 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1e3d0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1e3e0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1e3f0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1e400 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1e410 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1e420 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1e430 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1e440 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1e450 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1e460 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1e470 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1e480 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1e490 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1e4a0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1e4b0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1e4c0 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1e4d0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1e4e0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1e4f0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1e500 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1e510 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1e520 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1e530 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1e540 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1e550 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1e560 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1e570 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1e580 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1e590 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1e5a0 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1e5b0 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1e5c0 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1e5d0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1e5e0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1e5f0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1e600 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1e610 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1e620 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1e630 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1e640 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1e650 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1e660 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1e670 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1e680 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1e690 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1e6a0 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1e6b0 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1e6c0 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1e6d0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1e6e0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1e6f0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1e700 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1e710 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1e720 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1e730 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1e740 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1e750 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1e760 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1e770 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1e780 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1e790 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1e7a0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1e7b0 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1e7c0 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1e7d0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1e7e0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1e7f0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1e800 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1e810 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1e820 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1e830 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1e840 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1e850 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1e860 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1e870 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1e880 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1e890 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1e8a0 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1e8b0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1e8c0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1e8d0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1e8e0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1e8f0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1e900 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1e910 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1e920 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1e930 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1e940 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1e950 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1e960 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1e970 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1e980 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1e990 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1e9a0 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1e9b0 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1e9c0 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1e9d0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1e9e0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1e9f0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1ea00 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54  ring.)^.*/.SQLIT
1ea10 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c 69  E_API char *sqli
1ea20 74 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73  te3_mprintf(cons
1ea30 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 53 51  t char*,...);.SQ
1ea40 4c 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73  LITE_API char *s
1ea50 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28  qlite3_vmprintf(
1ea60 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f  const char*, va_
1ea70 6c 69 73 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  list);.SQLITE_AP
1ea80 49 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  I char *sqlite3_
1ea90 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1eaa0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1eab0 2e 2e 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  ...);.SQLITE_API
1eac0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76   char *sqlite3_v
1ead0 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
1eae0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
1eaf0 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a  va_list);../*.**
1eb00 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72   CAPI3REF: Memor
1eb10 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62  y Allocation Sub
1eb20 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65  system.**.** The
1eb30 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65   SQLite core use
1eb40 73 20 74 68 65 73 65 20 74 68 72 65 65 20 72 6f  s these three ro
1eb50 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f  utines for all o
1eb60 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74  f its own.** int
1eb70 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c  ernal memory all
1eb80 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22  ocation needs. "
1eb90 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70 72 65  Core" in the pre
1eba0 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a  vious sentence.*
1ebb0 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  * does not inclu
1ebc0 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  de operating-sys
1ebd0 74 65 6d 20 73 70 65 63 69 66 69 63 20 56 46 53  tem specific VFS
1ebe0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
1ebf0 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73    The.** Windows
1ec00 20 56 46 53 20 75 73 65 73 20 6e 61 74 69 76 65   VFS uses native
1ec10 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72   malloc() and fr
1ec20 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70  ee() for some op
1ec30 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  erations..**.** 
1ec40 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c  ^The sqlite3_mal
1ec50 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65  loc() routine re
1ec60 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
1ec70 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66  to a block.** of
1ec80 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74   memory at least
1ec90 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67   N bytes in leng
1eca0 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  th, where N is t
1ecb0 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  he parameter..**
1ecc0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c   ^If sqlite3_mal
1ecd0 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20  loc() is unable 
1ece0 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63  to obtain suffic
1ecf0 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d  ient free.** mem
1ed00 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20  ory, it returns 
1ed10 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
1ed20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d 65 74   ^If the paramet
1ed30 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  er N to.** sqlit
1ed40 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a  e3_malloc() is z
1ed50 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ero or negative 
1ed60 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c  then sqlite3_mal
1ed70 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a  loc() returns.**
1ed80 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1ed90 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20  .**.** ^Calling 
1eda0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77  sqlite3_free() w
1edb0 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72  ith a pointer pr
1edc0 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
1edd0 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f  d.** by sqlite3_
1ede0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1edf0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
1ee00 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f  leases that memo
1ee10 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74  ry so.** that it
1ee20 20 6d 69 67 68 74 20 62 65 20 72 65 75 73 65 64   might be reused
1ee30 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
1ee40 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69  free() routine i
1ee50 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20  s.** a no-op if 
1ee60 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61  is called with a
1ee70 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20   NULL pointer.  
1ee80 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70  Passing a NULL p
1ee90 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c  ointer.** to sql
1eea0 69 74 65 33 5f 66 72 65 65 28 29 20 69 73 20 68  ite3_free() is h
1eeb0 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20  armless.  After 
1eec0 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d  being freed, mem
1eed0 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65  ory.** should ne
1eee0 69 74 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f  ither be read no
1eef0 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e  r written.  Even
1ef00 20 72 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75   reading previou
1ef10 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d  sly freed.** mem
1ef20 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74  ory might result
1ef30 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69   in a segmentati
1ef40 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65  on fault or othe
1ef50 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a  r severe error..
1ef60 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70  ** Memory corrup
1ef70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61  tion, a segmenta
1ef80 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f  tion fault, or o
1ef90 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f  ther severe erro
1efa0 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c  r.** might resul
1efb0 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65  t if sqlite3_fre
1efc0 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69  e() is called wi
1efd0 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  th a non-NULL po
1efe0 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61  inter that.** wa
1eff0 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66  s not obtained f
1f000 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  rom sqlite3_mall
1f010 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  oc() or sqlite3_
1f020 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a  realloc()..**.**
1f030 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72   ^(The sqlite3_r
1f040 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61  ealloc() interfa
1f050 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72  ce attempts to r
1f060 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72  esize a.** prior
1f070 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1f080 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73  on to be at leas
1f090 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65  t N bytes, where
1f0a0 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63   N is the.** sec
1f0b0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20  ond parameter.  
1f0c0 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  The memory alloc
1f0d0 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69  ation to be resi
1f0e0 7a 65 64 20 69 73 20 74 68 65 20 66 69 72 73 74  zed is the first
1f0f0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e  .** parameter.)^
1f100 20 5e 20 49 66 20 74 68 65 20 66 69 72 73 74 20   ^ If the first 
1f110 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1f120 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a  ite3_realloc().*
1f130 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  * is a NULL poin
1f140 74 65 72 20 74 68 65 6e 20 69 74 73 20 62 65 68  ter then its beh
1f150 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63  avior is identic
1f160 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a  al to calling.**
1f170 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f180 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  N) where N is th
1f190 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
1f1a0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
1f1b0 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20  alloc()..** ^If 
1f1c0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1f1d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1f1e0 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  realloc() is zer
1f1f0 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65  o or.** negative
1f200 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1f210 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20 74 68  or is exactly th
1f220 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e  e same as callin
1f230 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65  g.** sqlite3_fre
1f240 65 28 50 29 20 77 68 65 72 65 20 50 20 69 73 20  e(P) where P is 
1f250 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
1f260 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
1f270 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71  ealloc()..** ^sq
1f280 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1f290 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1f2a0 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r to a memory al
1f2b0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61  location.** of a
1f2c0 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20  t least N bytes 
1f2d0 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20  in size or NULL 
1f2e0 69 66 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65  if sufficient me
1f2f0 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61  mory is unavaila
1f300 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73  ble..** ^If M is
1f310 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
1f320 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1f330 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29  n, then min(N,M)
1f340 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65   bytes.** of the
1f350 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
1f360 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74  n are copied int
1f370 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
1f380 6f 66 20 62 75 66 66 65 72 20 72 65 74 75 72 6e  of buffer return
1f390 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33  ed.** by sqlite3
1f3a0 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74  _realloc() and t
1f3b0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1f3c0 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a  ion is freed..**
1f3d0 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61   ^If sqlite3_rea
1f3e0 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e  lloc() returns N
1f3f0 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72  ULL, then the pr
1f400 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ior allocation.*
1f410 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a  * is not freed..
1f420 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1f430 79 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  y returned by sq
1f440 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61  lite3_malloc() a
1f450 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  nd sqlite3_reall
1f460 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79  oc().** is alway
1f470 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20  s aligned to at 
1f480 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74 65 20  least an 8 byte 
1f490 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20  boundary, or to 
1f4a0 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e  a.** 4 byte boun
1f4b0 64 61 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c  dary if the [SQL
1f4c0 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e  ITE_4_BYTE_ALIGN
1f4d0 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69  ED_MALLOC] compi
1f4e0 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f  le-time.** optio
1f4f0 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  n is used..**.**
1f500 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   In SQLite versi
1f510 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35  on 3.5.0 and 3.5
1f520 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69  .1, it was possi
1f530 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a  ble to define.**
1f540 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54   the SQLITE_OMIT
1f550 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49  _MEMORY_ALLOCATI
1f560 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63  ON which would c
1f570 61 75 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69  ause the built-i
1f580 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  n.** implementat
1f590 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75  ion of these rou
1f5a0 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74  tines to be omit
1f5b0 74 65 64 2e 20 20 54 68 61 74 20 63 61 70 61 62  ted.  That capab
1f5c0 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c  ility.** is no l
1f5d0 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20  onger provided. 
1f5e0 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d   Only built-in m
1f5f0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
1f600 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a   can be used..**
1f610 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53 51 4c  .** Prior to SQL
1f620 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e  ite version 3.7.
1f630 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77 73 20  10, the Windows 
1f640 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
1f650 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74 68 65  er called.** the
1f660 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29   system malloc()
1f670 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72 65   and free() dire
1f680 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65 72  ctly when conver
1f690 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  ting.** filename
1f6a0 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55 54  s between the UT
1f6b0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73 65  F-8 encoding use
1f6c0 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61  d by SQLite.** a
1f6d0 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c 65  nd whatever file
1f6e0 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69 73  name encoding is
1f6f0 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61 72   used by the par
1f700 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a  ticular Windows.
1f710 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e  ** installation.
1f720 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74    Memory allocat
1f730 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72 65 20  ion errors were 
1f740 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
1f750 20 74 68 65 79 20 77 65 72 65 20 72 65 70 6f 72   they were repor
1f760 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c  ted back as [SQL
1f770 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72  ITE_CANTOPEN] or
1f780 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  .** [SQLITE_IOER
1f790 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b  R] rather than [
1f7a0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a  SQLITE_NOMEM]..*
1f7b0 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  *.** The pointer
1f7c0 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73   arguments to [s
1f7d0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61  qlite3_free()] a
1f7e0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1f7f0 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62  loc()].** must b
1f800 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72  e either NULL or
1f810 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f   else pointers o
1f820 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70  btained from a p
1f830 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69  rior.** invocati
1f840 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1f850 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c  alloc()] or [sql
1f860 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
1f870 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74  that have.** not
1f880 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73   yet been releas
1f890 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  ed..**.** The ap
1f8a0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
1f8b0 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65  ot read or write
1f8c0 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20   any part of.** 
1f8d0 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72  a block of memor
1f8e0 79 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  y after it has b
1f8f0 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69  een released usi
1f900 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ng.** [sqlite3_f
1f910 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  ree()] or [sqlit
1f920 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  e3_realloc()]..*
1f930 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
1f940 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1f950 63 28 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41  c(int);.SQLITE_A
1f960 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
1f970 5f 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20  _realloc(void*, 
1f980 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
1f990 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72   void sqlite3_fr
1f9a0 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ee(void*);../*.*
1f9b0 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f  * CAPI3REF: Memo
1f9c0 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61  ry Allocator Sta
1f9d0 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51  tistics.**.** SQ
1f9e0 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74 68  Lite provides th
1f9f0 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63  ese two interfac
1fa00 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67  es for reporting
1fa10 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a   on the status.*
1fa20 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
1fa30 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71  3_malloc()], [sq
1fa40 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61  lite3_free()], a
1fa50 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c  nd [sqlite3_real
1fa60 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e  loc()].** routin
1fa70 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74  es, which form t
1fa80 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f  he built-in memo
1fa90 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
1faa0 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  bsystem..**.** ^
1fab0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  The [sqlite3_mem
1fac0 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74  ory_used()] rout
1fad0 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1fae0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a  number of bytes.
1faf0 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72  ** of memory cur
1fb00 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69  rently outstandi
1fb10 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74  ng (malloced but
1fb20 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20   not freed)..** 
1fb30 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1fb40 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
1fb50 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
1fb60 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a  s the maximum.**
1fb70 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74   value of [sqlit
1fb80 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
1fb90 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67 68  ] since the high
1fba0 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77  -water mark.** w
1fbb0 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20  as last reset.  
1fbc0 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74 75  ^The values retu
1fbd0 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1fbe0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1fbf0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
1fc00 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1fc10 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20  ()] include any 
1fc20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65  overhead.** adde
1fc30 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69  d by SQLite in i
1fc40 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ts implementatio
1fc50 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
1fc60 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20  lloc()],.** but 
1fc70 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64 64  not overhead add
1fc80 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e  ed by the any un
1fc90 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20  derlying system 
1fca0 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69  library.** routi
1fcb0 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65  nes that [sqlite
1fcc0 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20  3_malloc()] may 
1fcd0 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  call..**.** ^The
1fce0 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74   memory high-wat
1fcf0 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74  er mark is reset
1fd00 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
1fd10 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c  value of.** [sql
1fd20 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1fd30 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20  ()] if and only 
1fd40 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1fd50 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1fd60 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1fd70 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54  ()] is true.  ^T
1fd80 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
1fd90 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
1fda0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1fdb0 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69 67  r(1)] is the hig
1fdc0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1fdd0 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73  prior to the res
1fde0 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  et..*/.SQLITE_AP
1fdf0 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
1fe00 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1fe10 73 65 64 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54  sed(void);.SQLIT
1fe20 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
1fe30 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  t64 sqlite3_memo
1fe40 72 79 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74  ry_highwater(int
1fe50 20 72 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a   resetFlag);../*
1fe60 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73  .** CAPI3REF: Ps
1fe70 65 75 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62  eudo-Random Numb
1fe80 65 72 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a  er Generator.**.
1fe90 2a 2a 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69  ** SQLite contai
1fea0 6e 73 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74  ns a high-qualit
1feb0 79 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20  y pseudo-random 
1fec0 6e 75 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72  number generator
1fed0 20 28 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a   (PRNG) used to.
1fee0 2a 2a 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d  ** select random
1fef0 20 5b 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73   [ROWID | ROWIDs
1ff00 5d 20 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67  ] when inserting
1ff10 20 6e 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74   new records int
1ff20 6f 20 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a  o a table that.*
1ff30 2a 20 61 6c 72 65 61 64 79 20 75 73 65 73 20 74  * already uses t
1ff40 68 65 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69  he largest possi
1ff50 62 6c 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68  ble [ROWID].  Th
1ff60 65 20 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75  e PRNG is also u
1ff70 73 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62  sed for.** the b
1ff80 75 69 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29  uild-in random()
1ff90 20 61 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28   and randomblob(
1ffa0 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e  ) SQL functions.
1ffb0 20 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65    This interface
1ffc0 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69   allows.** appli
1ffd0 63 61 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73  cations to acces
1ffe0 73 20 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20  s the same PRNG 
1fff0 66 6f 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73  for other purpos
20000 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c  es..**.** ^A cal
20010 6c 20 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  l to this routin
20020 65 20 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73  e stores N bytes
20030 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69   of randomness i
20040 6e 74 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a  nto buffer P..**
20050 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74  .** ^The first t
20060 69 6d 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ime this routine
20070 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74   is invoked (eit
20080 68 65 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f  her internally o
20090 72 20 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c  r by.** the appl
200a0 69 63 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e  ication) the PRN
200b0 47 20 69 73 20 73 65 65 64 65 64 20 75 73 69 6e  G is seeded usin
200c0 67 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74  g randomness obt
200d0 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68  ained.** from th
200e0 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65  e xRandomness me
200f0 74 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61  thod of the defa
20100 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
20110 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e  ] object..** ^On
20120 20 61 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20   all subsequent 
20130 69 6e 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65  invocations, the
20140 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65   pseudo-randomne
20150 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a  ss is generated.
20160 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e  ** internally an
20170 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72  d without recour
20180 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  se to the [sqlit
20190 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e  e3_vfs] xRandomn
201a0 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a  ess.** method..*
201b0 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  /.SQLITE_API voi
201c0 64 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d  d sqlite3_random
201d0 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64  ness(int N, void
201e0 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50   *P);../*.** CAP
201f0 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54  I3REF: Compile-T
20200 69 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  ime Authorizatio
20210 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
20220 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
20230 72 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74  registers an aut
20240 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
20250 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
20260 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
20270 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70  connection], sup
20280 70 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  plied in the fir
20290 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  st argument..** 
202a0 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20  ^The authorizer 
202b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
202c0 6b 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65  ked as SQL state
202d0 6d 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20  ments are being 
202e0 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b  compiled.** by [
202f0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
20300 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e  )] or its varian
20310 74 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ts [sqlite3_prep
20320 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73  are_v2()],.** [s
20330 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20340 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
20350 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
20360 2e 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a  .  ^At various.*
20370 2a 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20  * points during 
20380 74 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20  the compilation 
20390 70 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69  process, as logi
203a0 63 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74  c is being creat
203b0 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d  ed.** to perform
203c0 20 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73   various actions
203d0 2c 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  , the authorizer
203e0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
203f0 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69  oked to.** see i
20400 66 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20  f those actions 
20410 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54  are allowed.  ^T
20420 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
20430 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a  llback should.**
20440 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
20450 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65  OK] to allow the
20460 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45   action, [SQLITE
20470 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61  _IGNORE] to disa
20480 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63  llow the.** spec
20490 69 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20  ific action but 
204a0 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74  allow the SQL st
204b0 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69  atement to conti
204c0 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  nue to be.** com
204d0 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54  piled, or [SQLIT
204e0 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65  E_DENY] to cause
204f0 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20   the entire SQL 
20500 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a  statement to be.
20510 2a 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68  ** rejected with
20520 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20   an error.  ^If 
20530 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
20540 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a  allback returns.
20550 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68  ** any value oth
20560 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
20570 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45  IGNORE], [SQLITE
20580 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  _OK], or [SQLITE
20590 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74  _DENY].** then t
205a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
205b0 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75  are_v2()] or equ
205c0 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61  ivalent call tha
205d0 74 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74  t triggered.** t
205e0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69  he authorizer wi
205f0 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20  ll fail with an 
20600 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a  error message..*
20610 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61  *.** When the ca
20620 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b  llback returns [
20630 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74  SQLITE_OK], that
20640 20 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61   means the opera
20650 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65  tion.** requeste
20660 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20  d is ok.  ^When 
20670 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
20680 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e  urns [SQLITE_DEN
20690 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Y], the.** [sqli
206a0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
206b0 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20  ] or equivalent 
206c0 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65  call that trigge
206d0 72 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f  red the.** autho
206e0 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20  rizer will fail 
206f0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65  with an error me
20700 73 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67  ssage explaining
20710 20 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20   that.** access 
20720 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a  is denied. .**.*
20730 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72  * ^The first par
20740 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75  ameter to the au
20750 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
20760 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
20770 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61  he third.** para
20780 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
20790 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
207a0 7a 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e  zer() interface.
207b0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
207c0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
207d0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
207e0 69 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f  integer [SQLITE_
207f0 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f  COPY | action co
20800 64 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69  de] that specifi
20810 65 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63  es.** the partic
20820 75 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62  ular action to b
20830 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54  e authorized. ^T
20840 68 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68  he third through
20850 20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72   sixth parameter
20860 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c  s.** to the call
20870 62 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65  back are zero-te
20880 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73  rminated strings
20890 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64   that contain ad
208a0 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61  ditional.** deta
208b0 69 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63  ils about the ac
208c0 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
208d0 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  rized..**.** ^If
208e0 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65   the action code
208f0 20 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44   is [SQLITE_READ
20900 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c  ].** and the cal
20910 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
20920 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68  QLITE_IGNORE] th
20930 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  en the.** [prepa
20940 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73  red statement] s
20950 74 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73  tatement is cons
20960 74 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74  tructed to subst
20970 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20  itute.** a NULL 
20980 76 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f  value in place o
20990 66 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75  f the table colu
209a0 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61  mn that would ha
209b0 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20  ve.** been read 
209c0 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68  if [SQLITE_OK] h
209d0 61 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64  ad been returned
209e0 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49  .  The [SQLITE_I
209f0 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e  GNORE].** return
20a00 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
20a10 64 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65  deny an untruste
20a20 64 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f  d user access to
20a30 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63   individual.** c
20a40 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c  olumns of a tabl
20a50 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  e..** ^If the ac
20a60 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
20a70 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64  LITE_DELETE] and
20a80 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65   the callback re
20a90 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  turns.** [SQLITE
20aa0 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68  _IGNORE] then th
20ab0 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61  e [DELETE] opera
20ac0 74 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75  tion proceeds bu
20ad0 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61  t the.** [trunca
20ae0 74 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d  te optimization]
20af0 20 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64   is disabled and
20b00 20 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65   all rows are de
20b10 6c 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c  leted individual
20b20 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74  ly..**.** An aut
20b30 68 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20  horizer is used 
20b40 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  when [sqlite3_pr
20b50 65 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e  epare | preparin
20b60 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  g].** SQL statem
20b70 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74  ents from an unt
20b80 72 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74  rusted source, t
20b90 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68  o ensure that th
20ba0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
20bb0 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74  .** do not try t
20bc0 6f 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68  o access data th
20bd0 65 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77  ey are not allow
20be0 65 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68  ed to see, or th
20bf0 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
20c00 2a 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65  * try to execute
20c10 20 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65   malicious state
20c20 6d 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67  ments that damag
20c30 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  e the database. 
20c40 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c   For.** example,
20c50 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
20c60 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72  may allow a user
20c70 20 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72   to enter arbitr
20c80 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69  ary.** SQL queri
20c90 65 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f  es for evaluatio
20ca0 6e 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e  n by a database.
20cb0 20 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63    But the applic
20cc0 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f  ation does.** no
20cd0 74 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20  t want the user 
20ce0 74 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61  to be able to ma
20cf0 6b 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61  ke arbitrary cha
20d00 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64  nges to the.** d
20d10 61 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74  atabase.  An aut
20d20 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68  horizer could th
20d30 65 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61  en be put in pla
20d40 63 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20  ce while the.** 
20d50 75 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c  user-entered SQL
20d60 20 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74   is being [sqlit
20d70 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65  e3_prepare | pre
20d80 70 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64  pared] that.** d
20d90 69 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68  isallows everyth
20da0 69 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45  ing except [SELE
20db0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  CT] statements..
20dc0 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f  **.** Applicatio
20dd0 6e 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20  ns that need to 
20de0 70 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d  process SQL from
20df0 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63   untrusted sourc
20e00 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f  es.** might also
20e10 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69   consider loweri
20e20 6e 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69  ng resource limi
20e30 74 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ts using [sqlite
20e40 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e  3_limit()].** an
20e50 64 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62  d limiting datab
20e60 61 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74  ase size using t
20e70 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75  he [max_page_cou
20e80 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20  nt] [PRAGMA].** 
20e90 69 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75  in addition to u
20ea0 73 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a  sing an authoriz
20eb0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79  er..**.** ^(Only
20ec0 20 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72   a single author
20ed0 69 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70  izer can be in p
20ee0 6c 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61  lace on a databa
20ef0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
20f00 20 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63   at a time.  Eac
20f10 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  h call to sqlite
20f20 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
20f30 20 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a   overrides the.*
20f40 2a 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e  * previous call.
20f50 29 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65  )^  ^Disable the
20f60 20 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69   authorizer by i
20f70 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c  nstalling a NULL
20f80 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68   callback..** Th
20f90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20  e authorizer is 
20fa0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
20fb0 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61  ult..**.** The a
20fc0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
20fd0 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
20fe0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
20ff0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
21000 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21010 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
21020 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21030 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74  callback..** Not
21040 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
21050 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
21060 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
21070 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
21080 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
21090 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
210a0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
210b0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
210c0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
210d0 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33  * ^When [sqlite3
210e0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69  _prepare_v2()] i
210f0 73 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72  s used to prepar
21100 65 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74  e a statement, t
21110 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  he.** statement 
21120 6d 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70  might be re-prep
21130 61 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c  ared during [sql
21140 69 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65  ite3_step()] due
21150 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61   to a .** schema
21160 20 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c   change.  Hence,
21170 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
21180 20 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74   should ensure t
21190 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65  hat the.** corre
211a0 63 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  ct authorizer ca
211b0 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69  llback remains i
211c0 6e 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74  n place during t
211d0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  he [sqlite3_step
211e0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65  ()]..**.** ^Note
211f0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
21200 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
21210 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75   invoked only du
21220 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ring.** [sqlite3
21230 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
21240 74 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75  ts variants.  Au
21250 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e  thorization is n
21260 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ot.** performed 
21270 64 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74  during statement
21280 20 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b   evaluation in [
21290 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c  sqlite3_step()],
212a0 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74   unless.** as st
212b0 61 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76  ated in the prev
212c0 69 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20  ious paragraph, 
212d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
212e0 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65  nvokes.** sqlite
212f0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74  3_prepare_v2() t
21300 6f 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74  o reprepare a st
21310 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20  atement after a 
21320 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a  schema change..*
21330 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
21340 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74   sqlite3_set_aut
21350 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74  horizer(.  sqlit
21360 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75  e3*,.  int (*xAu
21370 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  th)(void*,int,co
21380 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
21390 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
213a0 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a  *,const char*),.
213b0 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74    void *pUserDat
213c0 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  a.);../*.** CAPI
213d0 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72  3REF: Authorizer
213e0 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a   Return Codes.**
213f0 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33  .** The [sqlite3
21400 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
21410 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  | authorizer cal
21420 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20  lback function] 
21430 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65  must.** return e
21440 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b  ither [SQLITE_OK
21450 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73  ] or one of thes
21460 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20  e two constants 
21470 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73  in order.** to s
21480 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65  ignal SQLite whe
21490 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
214a0 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74  action is permit
214b0 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ted.  See the.**
214c0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
214d0 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f  thorizer | autho
214e0 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74  rizer documentat
214f0 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f  ion] for additio
21500 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
21510 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  on..**.** Note t
21520 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  hat SQLITE_IGNOR
21530 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61  E is also used a
21540 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c  s a [SQLITE_ROLL
21550 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f  BACK | return co
21560 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  de].** from the 
21570 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e  [sqlite3_vtab_on
21580 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74  _conflict()] int
21590 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69  erface..*/.#defi
215a0 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20  ne SQLITE_DENY  
215b0 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68   1   /* Abort th
215c0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
215d0 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f  with an error */
215e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
215f0 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f  IGNORE 2   /* Do
21600 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73  n't allow access
21610 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65  , but don't gene
21620 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f  rate an error */
21630 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
21640 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74  : Authorizer Act
21650 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ion Codes.**.** 
21660 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  The [sqlite3_set
21670 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69  _authorizer()] i
21680 6e 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65  nterface registe
21690 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  rs a callback fu
216a0 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69  nction.** that i
216b0 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74  s invoked to aut
216c0 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53  horize certain S
216d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74  QL statement act
216e0 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65  ions.  The.** se
216f0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74  cond parameter t
21700 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  o the callback i
21710 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  s an integer cod
21720 65 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73  e that specifies
21730 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20  .** what action 
21740 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69  is being authori
21750 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72 65 20  zed.  These are 
21760 74 68 65 20 69 6e 74 65 67 65 72 20 61 63 74 69  the integer acti
21770 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a  on codes that.**
21780 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
21790 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20  callback may be 
217a0 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  passed..**.** Th
217b0 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  ese action code 
217c0 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77  values signify w
217d0 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72  hat kind of oper
217e0 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a  ation is to be.*
217f0 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54  * authorized.  T
21800 68 65 20 33 72 64 20 61 6e 64 20 34 74 68 20 70  he 3rd and 4th p
21810 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65  arameters to the
21820 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a   authorization.*
21830 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  * callback funct
21840 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61  ion will be para
21850 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64  meters or NULL d
21860 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63  epending on whic
21870 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f  h of these.** co
21880 64 65 73 20 69 73 20 75 73 65 64 20 61 73 20 74  des is used as t
21890 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
218a0 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20  ter.  ^(The 5th 
218b0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
218c0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63  .** authorizer c
218d0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
218e0 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
218f0 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65  ase ("main", "te
21900 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66  mp",.** etc.) if
21910 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20   applicable.)^  
21920 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d 65 74  ^The 6th paramet
21930 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72  er to the author
21940 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  izer callback.**
21950 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
21960 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74  the inner-most t
21970 72 69 67 67 65 72 20 6f 72 20 76 69 65 77 20 74  rigger or view t
21980 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62  hat is responsib
21990 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63  le for.** the ac
219a0 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20  cess attempt or 
219b0 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63  NULL if this acc
219c0 65 73 73 20 61 74 74 65 6d 70 74 20 69 73 20 64  ess attempt is d
219d0 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20  irectly from.** 
219e0 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f  top-level SQL co
219f0 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a  de..*/./********
21a00 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21a10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
21a20 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a  *** 3rd ********
21a30 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a  **** 4th *******
21a40 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ****/.#define SQ
21a50 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45  LITE_CREATE_INDE
21a60 58 20 20 20 20 20 20 20 20 20 20 31 20 20 20 2f  X          1   /
21a70 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
21a80 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
21a90 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21aa0 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45  ITE_CREATE_TABLE
21ab0 20 20 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a            2   /*
21ac0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21ad0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21ae0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21af0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49  TE_CREATE_TEMP_I
21b00 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20  NDEX     3   /* 
21b10 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
21b20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
21b30 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
21b40 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41  E_CREATE_TEMP_TA
21b50 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54  BLE     4   /* T
21b60 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
21b70 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
21b80 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
21b90 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49  _CREATE_TEMP_TRI
21ba0 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72  GGER   5   /* Tr
21bb0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
21bc0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
21bd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
21be0 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57  CREATE_TEMP_VIEW
21bf0 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65        6   /* Vie
21c00 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
21c10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
21c20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
21c30 52 45 41 54 45 5f 54 52 49 47 47 45 52 20 20 20  REATE_TRIGGER   
21c40 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67       7   /* Trig
21c50 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
21c60 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
21c70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
21c80 45 41 54 45 5f 56 49 45 57 20 20 20 20 20 20 20  EATE_VIEW       
21c90 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20      8   /* View 
21ca0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
21cb0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
21cc0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c  efine SQLITE_DEL
21cd0 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ETE             
21ce0 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20     9   /* Table 
21cf0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
21d00 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
21d10 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
21d20 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20 20  _INDEX          
21d30 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   10   /* Index N
21d40 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
21d50 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
21d60 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
21d70 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 20  TABLE           
21d80 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  11   /* Table Na
21d90 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
21da0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
21db0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
21dc0 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31  EMP_INDEX      1
21dd0 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  2   /* Index Nam
21de0 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
21df0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
21e00 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
21e10 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33  MP_TABLE      13
21e20 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
21e30 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
21e40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
21e50 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
21e60 50 5f 54 52 49 47 47 45 52 20 20 20 20 31 34 20  P_TRIGGER    14 
21e70 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
21e80 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
21e90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
21ea0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
21eb0 5f 56 49 45 57 20 20 20 20 20 20 20 31 35 20 20  _VIEW       15  
21ec0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
21ed0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
21ee0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
21ef0 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47  QLITE_DROP_TRIGG
21f00 45 52 20 20 20 20 20 20 20 20 20 31 36 20 20 20  ER         16   
21f10 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
21f20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
21f30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
21f40 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20  LITE_DROP_VIEW  
21f50 20 20 20 20 20 20 20 20 20 20 31 37 20 20 20 2f            17   /
21f60 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
21f70 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
21f80 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
21f90 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20  ITE_INSERT      
21fa0 20 20 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a           18   /*
21fb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
21fc0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
21fd0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
21fe0 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TE_PRAGMA       
21ff0 20 20 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20          19   /* 
22000 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20  Pragma Name     
22010 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20  1st arg or NULL 
22020 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22030 45 5f 52 45 41 44 20 20 20 20 20 20 20 20 20 20  E_READ          
22040 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54         20   /* T
22050 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43  able Name      C
22060 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a  olumn Name     *
22070 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22080 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20  _SELECT         
22090 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55        21   /* NU
220a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 4e 55  LL            NU
220b0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
220c0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
220d0 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20  TRANSACTION     
220e0 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65       22   /* Ope
220f0 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c  ration       NUL
22100 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22110 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
22120 50 44 41 54 45 20 20 20 20 20 20 20 20 20 20 20  PDATE           
22130 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c      23   /* Tabl
22140 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75  e Name      Colu
22150 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  mn Name     */.#
22160 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54  define SQLITE_AT
22170 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20  TACH            
22180 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e     24   /* Filen
22190 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20  ame        NULL 
221a0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
221b0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54  efine SQLITE_DET
221c0 41 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20  ACH             
221d0 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61    25   /* Databa
221e0 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20  se Name   NULL  
221f0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22200 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45  fine SQLITE_ALTE
22210 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  R_TABLE         
22220 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73   26   /* Databas
22230 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e  e Name   Table N
22240 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22250 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44  ine SQLITE_REIND
22260 45 58 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EX              
22270 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61  27   /* Index Na
22280 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
22290 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
222a0 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a  ne SQLITE_ANALYZ
222b0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32  E              2
222c0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
222d0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
222e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
222f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22300 56 54 41 42 4c 45 20 20 20 20 20 20 20 20 32 39  VTABLE        29
22310 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
22320 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d        Module Nam
22330 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  e     */.#define
22340 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41   SQLITE_DROP_VTA
22350 42 4c 45 20 20 20 20 20 20 20 20 20 20 33 30 20  BLE          30 
22360 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22370 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65       Module Name
22380 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22390 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20  SQLITE_FUNCTION 
223a0 20 20 20 20 20 20 20 20 20 20 20 20 33 31 20 20              31  
223b0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
223c0 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d      Function Nam
223d0 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e   */.#define S
223e0 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20  QLITE_SAVEPOINT 
223f0 20 20 20 20 20 20 20 20 20 20 20 33 32 20 20 20             32   
22400 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
22410 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d     Savepoint Nam
22420 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e  */.#define SQ
22430 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20  LITE_COPY       
22440 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
22450 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64  * No longer used
22460 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
22470 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64  REF: Tracing And
22480 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74   Profiling Funct
22490 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
224a0 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74   routines regist
224b0 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
224c0 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62  tions that can b
224d0 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72  e used for.** tr
224e0 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c  acing and profil
224f0 69 6e 67 20 74 68 65 20 65 78 65 63 75 74 69 6f  ing the executio
22500 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65  n of SQL stateme
22510 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
22520 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
22530 6e 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20  n registered by 
22540 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22550 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a  is invoked at.**
22560 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77   various times w
22570 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65  hen an SQL state
22580 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75  ment is being ru
22590 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74  n by [sqlite3_st
225a0 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73  ep()]..** ^The s
225b0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63  qlite3_trace() c
225c0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
225d0 65 64 20 77 69 74 68 20 61 20 55 54 46 2d 38 20  ed with a UTF-8 
225e0 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
225f0 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  .** SQL statemen
22600 74 20 74 65 78 74 20 61 73 20 74 68 65 20 73 74  t text as the st
22610 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65  atement first be
22620 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a  gins executing..
22630 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20  ** ^(Additional 
22640 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20  sqlite3_trace() 
22650 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20  callbacks might 
22660 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68  occur.** as each
22670 20 74 72 69 67 67 65 72 65 64 20 73 75 62 70 72   triggered subpr
22680 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64  ogram is entered
22690 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73  .  The callbacks
226a0 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a   for triggers.**
226b0 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38   contain a UTF-8
226c0 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61   SQL comment tha
226d0 74 20 69 64 65 6e 74 69 66 69 65 73 20 74 68 65  t identifies the
226e0 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a   trigger.)^.**.*
226f0 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
22700 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
22710 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70  red by sqlite3_p
22720 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f  rofile() is invo
22730 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53  ked.** as each S
22740 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e  QL statement fin
22750 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f  ishes.  ^The pro
22760 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f  file callback co
22770 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72  ntains.** the or
22780 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74  iginal statement
22790 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74   text and an est
227a0 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c  imate of wall-cl
227b0 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68  ock time.** of h
227c0 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61  ow long that sta
227d0 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72  tement took to r
227e0 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c  un.  ^The profil
227f0 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69  e callback.** ti
22800 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f  me is in units o
22810 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68  f nanoseconds, h
22820 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72 65  owever the curre
22830 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  nt implementatio
22840 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70  n.** is only cap
22850 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63  able of millisec
22860 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73  ond resolution s
22870 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74 20  o the six least 
22880 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64  significant.** d
22890 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d  igits in the tim
228a0 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73  e are meaningles
228b0 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  s.  Future versi
228c0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a  ons of SQLite.**
228d0 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20 67   might provide g
228e0 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f  reater resolutio
228f0 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65  n on the profile
22900 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65  r callback.  The
22910 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66  .** sqlite3_prof
22920 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ile() function i
22930 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70  s considered exp
22940 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73  erimental and is
22950 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63  .** subject to c
22960 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20  hange in future 
22970 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
22980 74 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  te..*/.SQLITE_AP
22990 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
229a0 74 72 61 63 65 28 73 71 6c 69 74 65 33 2a 2c 20  trace(sqlite3*, 
229b0 76 6f 69 64 28 2a 78 54 72 61 63 65 29 28 76 6f  void(*xTrace)(vo
229c0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  id*,const char*)
229d0 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45  , void*);.SQLITE
229e0 5f 41 50 49 20 53 51 4c 49 54 45 5f 45 58 50 45  _API SQLITE_EXPE
229f0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
22a00 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
22a10 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
22a20 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
22a30 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
22a40 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
22a50 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
22a60 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
22a70 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
22a80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
22a90 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
22aa0 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
22ab0 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
22ac0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
22ad0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
22ae0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
22af0 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
22b00 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
22b10 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
22b20 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
22b30 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
22b40 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
22b50 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
22b60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
22b70 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
22b80 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
22b90 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
22ba0 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
22bb0 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
22bc0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
22bd0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
22be0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
22bf0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
22c00 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
22c10 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
22c20 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
22c30 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e 75 6d  ter N is the num
22c40 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69 72 74  ber of .** [virt
22c50 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e 73 74  ual machine inst
22c60 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74 20 61  ructions] that a
22c70 72 65 20 65 76 61 6c 75 61 74 65 64 20 62 65 74  re evaluated bet
22c80 77 65 65 6e 20 73 75 63 63 65 73 73 69 76 65 0a  ween successive.
22c90 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  ** invocations o
22ca0 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 58  f the callback X
22cb0 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20  ..**.** ^Only a 
22cc0 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20  single progress 
22cd0 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64  handler may be d
22ce0 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69  efined at one ti
22cf0 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62  me per.** [datab
22d00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b  ase connection];
22d10 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70   setting a new p
22d20 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
22d30 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f  cancels the.** o
22d40 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e  ld one.  ^Settin
22d50 67 20 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f  g parameter X to
22d60 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74   NULL disables t
22d70 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
22d80 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f  ler..** ^The pro
22d90 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73  gress handler is
22da0 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62   also disabled b
22db0 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61  y setting N to a
22dc0 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74   value less.** t
22dd0 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  han 1..**.** ^If
22de0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 63 61   the progress ca
22df0 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
22e00 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65  on-zero, the ope
22e10 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74  ration is.** int
22e20 65 72 72 75 70 74 65 64 2e 20 20 54 68 69 73 20  errupted.  This 
22e30 66 65 61 74 75 72 65 20 63 61 6e 20 62 65 20 75  feature can be u
22e40 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
22e50 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62   a.** "Cancel" b
22e60 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70  utton on a GUI p
22e70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62  rogress dialog b
22e80 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72  ox..**.** The pr
22e90 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63  ogress handler c
22ea0 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74  allback must not
22eb0 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61   do anything tha
22ec0 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a  t will modify.**
22ed0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
22ee0 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e  nnection that in
22ef0 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65  voked the progre
22f00 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e  ss handler..** N
22f10 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65  ote that [sqlite
22f20 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
22f30 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  and [sqlite3_ste
22f40 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79  p()] both modify
22f50 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61   their.** databa
22f60 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
22f70 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
22f80 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
22f90 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
22fa0 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  .*/.SQLITE_API v
22fb0 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
22fc0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
22fd0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
22fe0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
22ff0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23000 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
23010 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
23020 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
23030 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
23040 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
23050 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
23060 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
23070 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
23080 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
23090 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
230a0 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
230b0 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
230c0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
230d0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
230e0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
230f0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
23100 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
23110 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
23120 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
23130 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
23140 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
23150 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
23160 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
23170 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
23180 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
23190 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
231a0 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
231b0 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
231c0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
231d0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
231e0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
231f0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
23200 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
23210 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
23220 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
23230 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
23240 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
23250 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
23260 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
23270 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
23280 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
23290 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
232a0 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
232b0 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
232c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
232d0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
232e0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
232f0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
23300 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
23310 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
23320 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
23330 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
23340 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
23350 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
23360 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
23370 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
23380 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
23390 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
233a0 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
233b0 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
233c0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
233d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
233e0 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
233f0 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
23400 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
23410 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
23420 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
23430 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
23440 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
23450 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
23460 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
23470 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
23480 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
23490 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
234a0 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
234b0 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
234c0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
234d0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
234e0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
234f0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
23500 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
23510 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
23520 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
23530 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
23540 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
23550 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
23560 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
23570 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
23580 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
23590 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
235a0 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
235b0 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
235c0 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
235d0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
235e0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
235f0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
23600 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
23610 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
23620 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
23630 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
23640 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
23650 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
23660 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
23670 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
23680 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
23690 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
236a0 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
236b0 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
236c0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
236d0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
236e0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
236f0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
23700 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
23710 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
23720 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
23730 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
23740 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
23750 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
23760 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
23770 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
23780 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
23790 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
237a0 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
237b0 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
237c0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
237d0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
237e0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
237f0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
23800 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
23810 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
23820 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
23830 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
23840 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
23850 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
23860 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
23870 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
23880 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
23890 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
238a0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
238b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
238c0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
238d0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
238e0 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
238f0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
23900 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
23910 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
23920 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
23930 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
23940 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
23950 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
23960 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
23970 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
23980 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
23990 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
239a0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
239b0 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
239c0 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
239d0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
239e0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
239f0 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
23a00 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
23a10 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
23a20 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
23a30 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
23a40 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
23a50 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
23a60 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
23a70 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
23a80 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
23a90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
23aa0 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
23ab0 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
23ac0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
23ad0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
23ae0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
23af0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
23b00 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
23b10 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
23b20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
23b30 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
23b40 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
23b50 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
23b60 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
23b70 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
23b80 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
23b90 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
23ba0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
23bb0 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
23bc0 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
23bd0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
23be0 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
23bf0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
23c00 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
23c10 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
23c20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
23c30 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
23c40 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
23c50 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
23c60 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
23c70 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
23c80 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
23c90 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
23ca0 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
23cb0 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
23cc0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
23cd0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
23ce0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
23cf0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23d00 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
23d10 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
23d20 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
23d30 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
23d40 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
23d50 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
23d60 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
23d70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
23d80 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
23d90 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
23da0 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
23db0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
23dc0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
23dd0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
23de0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23df0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
23e00 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
23e10 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
23e20 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
23e30 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
23e40 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
23e50 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
23e60 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
23e70 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
23e80 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
23e90 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
23ea0 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
23eb0 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
23ec0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
23ed0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
23ee0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
23ef0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
23f00 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
23f10 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
23f20 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
23f30 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
23f40 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
23f50 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
23f60 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
23f70 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
23f80 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
23f90 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
23fa0 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
23fb0 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
23fc0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
23fd0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
23fe0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
23ff0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
24000 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
24010 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
24020 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
24030 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
24040 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
24050 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
24060 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
24070 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
24080 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
24090 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
240a0 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
240b0 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
240c0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
240d0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
240e0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
240f0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
24100 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
24110 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
24120 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
24130 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
24140 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
24150 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
24160 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
24170 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
24180 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
24190 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
241a0 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
241b0 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
241c0 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
241d0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
241e0 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
241f0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
24200 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
24210 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
24220 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
24230 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
24240 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
24250 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
24260 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
24270 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
24280 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
24290 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
242a0 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
242b0 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
242c0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
242d0 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
242e0 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
242f0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
24300 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
24310 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
24320 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
24330 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
24340 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
24350 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
24360 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
24370 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
24380 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
24390 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
243a0 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
243b0 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
243c0 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
243d0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
243e0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
243f0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
24400 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
24410 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
24420 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
24430 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
24440 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
24450 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
24460 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
24470 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
24480 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
24490 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
244a0 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
244b0 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
244c0 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
244d0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
244e0 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
244f0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
24500 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
24510 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
24520 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
24530 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
24540 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
24550 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
24560 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
24570 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
24580 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
24590 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
245a0 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
245b0 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
245c0 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
245d0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
245e0 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
245f0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
24600 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
24610 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
24620 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
24630 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
24640 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
24650 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
24660 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
24670 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
24680 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
24690 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77  . .** ^On window
246a0 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
246b0 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
246c0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
246d0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
246e0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
246f0 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  :")..**.** [[cor
24700 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
24710 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
24720 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
24730 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
24740 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
24750 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
24760 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
24770 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
24780 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
24790 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
247a0 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
247b0 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
247c0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
247d0 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d  hree query param
247e0 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
247f0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
24800 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
24810 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
24820 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
24830 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
24840 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
24850 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
24860 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
24870 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
24880 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
24890 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
248a0 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
248b0 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
248c0 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
248d0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
248e0 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
248f0 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
24900 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
24910 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
24920 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
24930 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
24940 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
24950 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
24960 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
24970 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
24980 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
24990 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
249a0 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
249b0 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
249c0 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
249d0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
249e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
249f0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
24a00 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
24a10 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
24a20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
24a30 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
24a40 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
24a50 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
24a60 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
24a70 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
24a80 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
24a90 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
24aa0 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
24ab0 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
24ac0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
24ad0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
24ae0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
24af0 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
24b00 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
24b10 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
24b20 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
24b30 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
24b40 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
24b50 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
24b60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
24b70 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
24b80 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
24b90 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
24ba0 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
24bb0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
24bc0 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
24bd0 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
24be0 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
24bf0 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
24c00 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
24c10 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
24c20 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
24c30 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
24c40 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
24c50 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
24c60 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
24c70 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
24c80 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
24c90 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
24ca0 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
24cb0 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
24cc0 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
24cd0 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
24ce0 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
24cf0 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
24d00 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
24d10 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
24d20 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
24d30 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
24d40 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
24d50 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
24d60 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
24d70 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
24d80 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
24d90 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
24da0 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
24db0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
24dc0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
24dd0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
24de0 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
24df0 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
24e00 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
24e10 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
24e20 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
24e30 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
24e40 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
24e50 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
24e60 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
24e70 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
24e80 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
24e90 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
24ea0 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
24eb0 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
24ec0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
24ed0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
24ee0 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
24ef0 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
24f00 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
24f10 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
24f20 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
24f30 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
24f40 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
24f50 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
24f60 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
24f70 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
24f80 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
24f90 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
24fa0 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
24fb0 20 61 6e 79 20 62 65 68 61 76 69 6f 75 72 20 72   any behaviour r
24fc0 65 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74  equested by sett
24fd0 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54  ing.**     SQLIT
24fe0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
24ff0 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50  CHE or SQLITE_OP
25000 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66  EN_SHAREDCACHE f
25010 6c 61 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  lag..** </ul>.**
25020 0a 2a 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20  .** ^Specifying 
25030 61 6e 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d  an unknown param
25040 65 74 65 72 20 69 6e 20 74 68 65 20 71 75 65 72  eter in the quer
25050 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61  y component of a
25060 20 55 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a   URI is not an.*
25070 2a 20 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65  * error.  Future
25080 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
25090 69 74 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73  ite might unders
250a0 74 61 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20  tand additional 
250b0 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74  query.** paramet
250c0 65 72 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72  ers.  See "[quer
250d0 79 20 70 61 72 61 6d 65 74 65 72 73 20 77 69 74  y parameters wit
250e0 68 20 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e  h special meanin
250f0 67 20 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f  g to SQLite]" fo
25100 72 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20  r.** additional 
25110 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
25120 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
25130 65 20 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33  e examples]] <h3
25140 3e 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78  >URI filename ex
25150 61 6d 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a  amples</h3>.**.*
25160 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d  * <table border=
25170 22 31 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72  "1" align=center
25180 20 63 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a   cellpadding=5>.
25190 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20  ** <tr><th> URI 
251a0 66 69 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52  filenames <th> R
251b0 65 73 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74  esults.** <tr><t
251c0 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20  d> file:data.db 
251d0 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
251e0 20 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20    Open the file 
251f0 22 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65  "data.db" in the
25200 20 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f   current directo
25210 72 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ry..** <tr><td> 
25220 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
25230 64 61 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20  data.db<br>.**  
25240 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f          file:///
25250 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
25260 62 20 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20  b <br> .**      
25270 20 20 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c      file://local
25280 68 6f 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  host/home/fred/d
25290 61 74 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e  ata.db <br> <td>
252a0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
252b0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
252c0 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
252d0 2f 64 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74  /data.db"..** <t
252e0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61  r><td> file://da
252f0 72 6b 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64  rkstar/home/fred
25300 2f 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  /data.db <td> .*
25310 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72  *          An er
25320 72 6f 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20  ror. "darkstar" 
25330 69 73 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69  is not a recogni
25340 7a 65 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a  zed authority..*
25350 2a 20 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d  * <tr><td style=
25360 22 77 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77  "white-space:now
25370 72 61 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20  rap"> .**       
25380 20 20 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f     file:///C:/Do
25390 63 75 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30  cuments%20and%20
253a0 53 65 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65  Settings/fred/De
253b0 73 6b 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a  sktop/data.db.**
253c0 20 20 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77       <td> Window
253d0 73 20 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65  s only: Open the
253e0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
253f0 6f 6e 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f  on fred's deskto
25400 70 20 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20  p on drive.**   
25410 20 20 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20         C:. Note 
25420 74 68 61 74 20 74 68 65 20 25 32 30 20 65 73 63  that the %20 esc
25430 61 70 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78  aping in this ex
25440 61 6d 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72  ample is not str
25450 69 63 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20  ictly .**       
25460 20 20 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73     necessary - s
25470 70 61 63 65 20 63 68 61 72 61 63 74 65 72 73 20  pace characters 
25480 63 61 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65  can be used lite
25490 72 61 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20  rally.**        
254a0 20 20 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d    in URI filenam
254b0 65 73 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  es..** <tr><td> 
254c0 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64  file:data.db?mod
254d0 65 3d 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61  e=ro&cache=priva
254e0 74 65 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  te <td> .**     
254f0 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22       Open file "
25500 64 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20  data.db" in the 
25510 63 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72  current director
25520 79 20 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20  y for read-only 
25530 61 63 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20  access..**      
25540 20 20 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f      Regardless o
25550 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
25560 20 73 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f   shared-cache mo
25570 64 65 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79  de is enabled by
25580 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 64 65 66  .**          def
25590 61 75 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76  ault, use a priv
255a0 61 74 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74  ate cache..** <t
255b0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
255c0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76  e/fred/data.db?v
255d0 66 73 3d 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 20 3c  fs=unix-nolock <
255e0 74 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  td>.**          
255f0 4f 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65  Open file "/home
25600 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20  /fred/data.db". 
25610 55 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20  Use the special 
25620 56 46 53 20 22 75 6e 69 78 2d 6e 6f 6c 6f 63 6b  VFS "unix-nolock
25630 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  "..** <tr><td> f
25640 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
25650 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
25660 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
25670 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
25680 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
25690 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
256a0 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
256b0 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
256c0 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
256d0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
256e0 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
256f0 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
25700 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
25710 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
25720 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
25730 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
25740 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
25750 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
25760 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
25770 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
25780 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
25790 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
257a0 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
257b0 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
257c0 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
257d0 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
257e0 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
257f0 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
25800 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
25810 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
25820 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
25830 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
25840 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
25850 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
25860 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
25870 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
25880 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
25890 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
258a0 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
258b0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
258c0 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
258d0 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
258e0 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
258f0 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
25900 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
25910 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
25920 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
25930 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
25940 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
25950 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
25960 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
25970 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
25980 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
25990 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
259a0 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
259b0 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
259c0 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
259d0 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
259e0 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
259f0 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
25a00 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
25a10 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
25a20 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
25a30 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
25a40 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
25a50 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
25a60 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
25a70 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
25a80 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
25a90 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
25aa0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25ab0 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
25ac0 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
25ad0 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
25ae0 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
25af0 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
25b00 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
25b10 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
25b20 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
25b30 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
25b40 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a 20 20 63  qlite3_open(.  c
25b50 6f 6e 73 74 20 63 68 61 72 20 2a 66 69 6c 65 6e  onst char *filen
25b60 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61  ame,   /* Databa
25b70 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46  se filename (UTF
25b80 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  -8) */.  sqlite3
25b90 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
25ba0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
25bb0 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
25bc0 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
25bd0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
25be0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
25bf0 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
25c00 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
25c10 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
25c20 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
25c30 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
25c40 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
25c50 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
25c60 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
25c70 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
25c80 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
25c90 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
25ca0 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
25cb0 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
25cc0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
25cd0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
25ce0 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
25cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
25d00 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
25d10 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
25d20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
25d30 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
25d40 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
25d50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
25d60 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
25d70 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
25d80 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20  ese are utility 
25d90 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c  routines, useful
25da0 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
25db0 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
25dc0 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  eck.** to see if
25dd0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
25de0 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
25df0 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
25e00 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
25e10 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
25e20 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
25e30 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75  value of that qu
25e40 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
25e50 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65  *.** If F is the
25e60 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
25e70 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  me pointer passe
25e80 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
25e90 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a  () method of .**
25ea0 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
25eb0 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66  ation when the f
25ec0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
25ed0 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e  o xOpen() has on
25ee0 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66  e or .** more of
25ef0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
25f00 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54  N_URI] or [SQLIT
25f10 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20  E_OPEN_MAIN_DB] 
25f20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20  bits set and.** 
25f30 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  P is the name of
25f40 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d   the query param
25f50 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  eter, then.** sq
25f60 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
25f70 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
25f80 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
25f90 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  e P.** parameter
25fa0 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72   if it exists or
25fb0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
25fc0 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70  if P does not ap
25fd0 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75  pear as a .** qu
25fe0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  ery parameter on
25ff0 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71   F.  If P is a q
26000 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
26010 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78  f F.** has no ex
26020 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68  plicit value, th
26030 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
26040 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
26050 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  turns.** a point
26060 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  er to an empty s
26070 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
26080 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
26090 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
260a0 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ine assumes that
260b0 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a   P is a boolean.
260c0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  ** parameter and
260d0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
260e0 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61  ) or false (0) a
260f0 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
26100 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20  value.** of P.  
26110 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
26120 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
26130 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
26140 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a  rue (1) if the.*
26150 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79  * value of query
26160 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
26170 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74  one of "yes", "t
26180 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e  rue", or "on" in
26190 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20   any.** case or 
261a0 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
261b0 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ins with a non-z
261c0 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ero number.  The
261d0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69   .** sqlite3_uri
261e0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
261f0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73  routines returns
26200 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68   false (0) if th
26210 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75  e value of.** qu
26220 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
26230 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20  is one of "no", 
26240 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66  "false", or "off
26250 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72  " in any case or
26260 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65  .** if the value
26270 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
26280 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66  umeric zero.  If
26290 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72   P is not a quer
262a0 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
262b0 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61  n F or if the va
262c0 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73  lue of P is does
262d0 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f   not match any o
262e0 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20  f the.** above, 
262f0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
26300 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
26310 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a  returns (B!=0)..
26320 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26330 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c  3_uri_int64(F,P,
26340 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65  D) routine conve
26350 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rts the value of
26360 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d   P into a.** 64-
26370 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
26380 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
26390 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20  hat integer, or 
263a0 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a  D if P does not.
263b0 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68  ** exist.  If th
263c0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
263d0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
263e0 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c  than an integer,
263f0 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73   then.** zero is
26400 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a   returned..** .*
26410 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c  * If F is a NULL
26420 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73   pointer, then s
26430 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
26440 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
26450 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71  s NULL and.** sq
26460 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
26470 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
26480 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74   B.  If F is not
26490 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
264a0 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20  and.** is not a 
264b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61  database file pa
264c0 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74  thname pointer t
264d0 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65  hat SQLite passe
264e0 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
264f0 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20  .** VFS method, 
26500 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
26510 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  r of this routin
26520 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  e is undefined a
26530 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75  nd probably.** u
26540 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 53  ndesirable..*/.S
26550 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
26560 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 75 72  char *sqlite3_ur
26570 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f 6e 73  i_parameter(cons
26580 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d  t char *zFilenam
26590 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  e, const char *z
265a0 50 61 72 61 6d 29 3b 0a 53 51 4c 49 54 45 5f 41  Param);.SQLITE_A
265b0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 75  PI int sqlite3_u
265c0 72 69 5f 62 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74  ri_boolean(const
265d0 20 63 68 61 72 20 2a 7a 46 69 6c 65 2c 20 63 6f   char *zFile, co
265e0 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 72 61 6d  nst char *zParam
265f0 2c 20 69 6e 74 20 62 44 65 66 61 75 6c 74 29 3b  , int bDefault);
26600 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
26610 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
26620 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73  3_uri_int64(cons
26630 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63  t char*, const c
26640 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  har*, sqlite3_in
26650 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t64);.../*.** CA
26660 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
26670 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
26680 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
26690 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
266a0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
266b0 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
266c0 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
266d0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
266e0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
266f0 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65  ost recent faile
26700 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  d sqlite3_* API 
26710 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74  call.** associat
26720 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
26730 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
26740 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
26750 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62  call failed.** b
26760 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ut the most rece
26770 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
26780 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
26790 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20  n value from.** 
267a0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
267b0 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
267c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
267d0 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
267e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
267f0 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
26800 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
26810 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
26820 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
26830 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
26840 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
26850 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
26860 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
26870 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
26880 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
26890 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
268a0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
268b0 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
268c0 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
268d0 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
268e0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
268f0 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
26900 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
26910 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
26920 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
26930 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
26940 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
26950 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
26960 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
26970 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
26980 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
26990 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
269a0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
269b0 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
269c0 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
269d0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
269e0 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
269f0 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
26a00 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  .)^.**.** ^The s
26a10 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29 20  qlite3_errstr() 
26a20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
26a30 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61  s the English-la
26a40 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74  nguage text.** t
26a50 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
26a60 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c  e [result code],
26a70 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28   as UTF-8..** ^(
26a80 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
26a90 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
26aa0 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
26ab0 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  ed internally.**
26ac0 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65   and must not be
26ad0 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61 70   freed by the ap
26ae0 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a  plication)^..**.
26af0 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72 69  ** When the seri
26b00 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e  alized [threadin
26b10 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73  g mode] is in us
26b20 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20 74  e, it might be t
26b30 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20  he.** case that 
26b40 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f  a second error o
26b50 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72  ccurs on a separ
26b60 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62 65  ate thread in be
26b70 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d  tween.** the tim
26b80 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 65  e of the first e
26b90 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c  rror and the cal
26ba0 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72  l to these inter
26bb0 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74  faces..** When t
26bc0 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65  hat happens, the
26bd0 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69   second error wi
26be0 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20 73  ll be reported s
26bf0 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e  ince these.** in
26c00 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73 20  terfaces always 
26c10 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20  report the most 
26c20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20  recent result.  
26c30 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73  To avoid.** this
26c40 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63 61  , each thread ca
26c50 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69  n obtain exclusi
26c60 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64  ve use of the [d
26c70 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
26c80 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f  on] D.** by invo
26c90 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75  king [sqlite3_mu
26ca0 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69  tex_enter]([sqli
26cb0 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29  te3_db_mutex](D)
26cc0 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69  ) before beginni
26cd0 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61  ng.** to use D a
26ce0 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  nd invoking [sql
26cf0 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65  ite3_mutex_leave
26d00 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
26d10 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a  tex](D)) after.*
26d20 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74  * all calls to t
26d30 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69  he interfaces li
26d40 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63 6f  sted here are co
26d50 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  mpleted..**.** I
26d60 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66  f an interface f
26d70 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45  ails with SQLITE
26d80 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65  _MISUSE, that me
26d90 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  ans the interfac
26da0 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64  e.** was invoked
26db0 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20   incorrectly by 
26dc0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e  the application.
26dd0 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20    In that case, 
26de0 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64  the.** error cod
26df0 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61  e and message ma
26e00 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20  y or may not be 
26e10 73 65 74 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  set..*/.SQLITE_A
26e20 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  PI int sqlite3_e
26e30 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
26e40 64 62 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  db);.SQLITE_API 
26e50 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
26e60 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
26e70 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
26e80 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
26e90 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
26ea0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c 49  (sqlite3*);.SQLI
26eb0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
26ec0 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
26ed0 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53  g16(sqlite3*);.S
26ee0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
26ef0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65 72  char *sqlite3_er
26f00 72 73 74 72 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  rstr(int);../*.*
26f10 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
26f20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74  Statement Object
26f30 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
26f40 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26f50 74 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  t} {prepared sta
26f60 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41  tements}.**.** A
26f70 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
26f80 69 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73  is object repres
26f90 65 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51  ents a single SQ
26fa0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20  L statement..** 
26fb0 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76  This object is v
26fc0 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61  ariously known a
26fd0 73 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74  s a "prepared st
26fe0 61 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a  atement" or a.**
26ff0 20 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73   "compiled SQL s
27000 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d  tatement" or sim
27010 70 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d  ply as a "statem
27020 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ent"..**.** The 
27030 6c 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d  life of a statem
27040 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20  ent object goes 
27050 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74  something like t
27060 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  his:.**.** <ol>.
27070 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74  ** <li> Create t
27080 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20  he object using 
27090 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
270a0 5f 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61  _v2()] or a rela
270b0 74 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63  ted.**      func
270c0 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69  tion..** <li> Bi
270d0 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f  nd values to [ho
270e0 73 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75  st parameters] u
270f0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
27100 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20  _bind_*().**    
27110 20 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a    interfaces..**
27120 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51   <li> Run the SQ
27130 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71  L by calling [sq
27140 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e  lite3_step()] on
27150 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  e or more times.
27160 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74  .** <li> Reset t
27170 68 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  he statement usi
27180 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ng [sqlite3_rese
27190 74 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63  t()] then go bac
271a0 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65  k.**      to ste
271b0 70 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65  p 2.  Do this ze
271c0 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73  ro or more times
271d0 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f  ..** <li> Destro
271e0 79 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  y the object usi
271f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
27200 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c  lize()]..** </ol
27210 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f  >.**.** Refer to
27220 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f   documentation o
27230 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74  n individual met
27240 68 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61  hods above for a
27250 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
27260 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  ormation..*/.typ
27270 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
27280 74 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33  te3_stmt sqlite3
27290 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  _stmt;../*.** CA
272a0 50 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65  PI3REF: Run-time
272b0 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28   Limits.**.** ^(
272c0 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
272d0 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f  llows the size o
272e0 66 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72  f various constr
272f0 75 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74  ucts to be limit
27300 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65  ed.** on a conne
27310 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74  ction by connect
27320 69 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20  ion basis.  The 
27330 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
27340 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62  is the.** [datab
27350 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
27360 77 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74  whose limit is t
27370 6f 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72  o be set or quer
27380 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63  ied.  The.** sec
27390 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
273a0 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d   one of the [lim
273b0 69 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74  it categories] t
273c0 68 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20  hat define a.** 
273d0 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75  class of constru
273e0 63 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c  cts to be size l
273f0 69 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69  imited.  The thi
27400 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
27410 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74  the.** new limit
27420 20 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72   for that constr
27430 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66  uct.)^.**.** ^If
27440 20 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69   the new limit i
27450 73 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d  s a negative num
27460 62 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69  ber, the limit i
27470 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  s unchanged..** 
27480 5e 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74  ^(For each limit
27490 20 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45   category SQLITE
274a0 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f  _LIMIT_<i>NAME</
274b0 69 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a  i> there is a .*
274c0 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64  * [limits | hard
274d0 20 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a   upper bound].**
274e0 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d   set at compile-
274f0 74 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70  time by a C prep
27500 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63  rocessor macro c
27510 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73  alled.** [limits
27520 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69   | SQLITE_MAX_<i
27530 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28  >NAME</i>]..** (
27540 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e  The "_LIMIT_" in
27550 20 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61   the name is cha
27560 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e  nged to "_MAX_".
27570 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73  ))^.** ^Attempts
27580 20 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c   to increase a l
27590 69 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68  imit above its h
275a0 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20  ard upper bound 
275b0 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20  are.** silently 
275c0 74 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65  truncated to the
275d0 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
275e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64  d..**.** ^Regard
275f0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
27600 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74  or not the limit
27610 20 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68   was changed, th
27620 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c  e .** [sqlite3_l
27630 69 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63  imit()] interfac
27640 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72  e returns the pr
27650 69 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65  ior value of the
27660 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63   limit..** ^Henc
27670 65 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63  e, to find the c
27680 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
27690 61 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20  a limit without 
276a0 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20  changing it,.** 
276b0 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68  simply invoke th
276c0 69 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74  is interface wit
276d0 68 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  h the third para
276e0 6d 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e  meter set to -1.
276f0 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20  .**.** Run-time 
27700 6c 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e  limits are inten
27710 64 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61  ded for use in a
27720 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
27730 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20   manage.** both 
27740 74 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e  their own intern
27750 61 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  al database and 
27760 61 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74  also databases t
27770 68 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c  hat are controll
27780 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74  ed.** by untrust
27790 65 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72  ed external sour
277a0 63 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65  ces.  An example
277b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67   application mig
277c0 68 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62  ht be a.** web b
277d0 72 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20  rowser that has 
277e0 69 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65  its own database
277f0 73 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69  s for storing hi
27800 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70  story and.** sep
27810 61 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20  arate databases 
27820 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61  controlled by Ja
27830 76 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61  vaScript applica
27840 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64  tions downloaded
27850 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65  .** off the Inte
27860 72 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72  rnet.  The inter
27870 6e 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61  nal databases ca
27880 6e 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a  n be given the.*
27890 2a 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74  * large, default
278a0 20 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61   limits.  Databa
278b0 73 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65  ses managed by e
278c0 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20  xternal sources 
278d0 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20  can.** be given 
278e0 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d  much smaller lim
278f0 69 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20  its designed to 
27900 70 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c  prevent a denial
27910 20 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61   of service.** a
27920 74 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65  ttack.  Develope
27930 72 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61  rs might also wa
27940 6e 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73  nt to use the [s
27950 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
27960 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65  rizer()].** inte
27970 72 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72  rface to further
27980 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74   control untrust
27990 65 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a  ed SQL.  The siz
279a0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
279b0 65 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20  e.** created by 
279c0 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72  an untrusted scr
279d0 69 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61  ipt can be conta
279e0 69 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a  ined using the.*
279f0 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  * [max_page_coun
27a00 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a  t] [PRAGMA]..**.
27a10 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20  ** New run-time 
27a20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
27a30 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
27a40 20 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   future releases
27a50 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
27a60 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69  int sqlite3_limi
27a70 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
27a80 69 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b  id, int newVal);
27a90 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27aa0 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74  : Run-Time Limit
27ab0 20 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b   Categories.** K
27ac0 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20  EYWORDS: {limit 
27ad0 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69  category} {*limi
27ae0 74 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a  t categories}.**
27af0 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61  .** These consta
27b00 6e 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f  nts define vario
27b10 75 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c  us performance l
27b20 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61  imits.** that ca
27b30 6e 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20  n be lowered at 
27b40 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b  run-time using [
27b50 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
27b60 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69  ..** The synopsi
27b70 73 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67  s of the meaning
27b80 73 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73  s of the various
27b90 20 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e   limits is shown
27ba0 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74   below..** Addit
27bb0 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
27bc0 6e 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61  n is available a
27bd0 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69  t [limits | Limi
27be0 74 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a  ts in SQLite]..*
27bf0 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53  *.** <dl>.** [[S
27c00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47  QLITE_LIMIT_LENG
27c10 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
27c20 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f  E_LIMIT_LENGTH</
27c30 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
27c40 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61  aximum size of a
27c50 6e 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f  ny string or BLO
27c60 42 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20  B or table row, 
27c70 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a  in bytes.<dd>)^.
27c80 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
27c90 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d  IMIT_SQL_LENGTH]
27ca0 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27cb0 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
27cc0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27cd0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
27ce0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
27cf0 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
27d00 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  d>)^.**.** [[SQL
27d10 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e  ITE_LIMIT_COLUMN
27d20 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
27d30 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74  LIMIT_COLUMN</dt
27d40 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
27d50 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
27d60 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c  olumns in a tabl
27d70 65 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20  e definition or 
27d80 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  in the.** result
27d90 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
27da0 54 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75  T] or the maximu
27db0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  m number of colu
27dc0 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a  mns in an index.
27dd0 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45  ** or in an ORDE
27de0 52 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59  R BY or GROUP BY
27df0 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a   clause.</dd>)^.
27e00 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
27e10 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d  IMIT_EXPR_DEPTH]
27e20 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27e30 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c  IMIT_EXPR_DEPTH<
27e40 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
27e50 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
27e60 20 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20   the parse tree 
27e70 6f 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f  on any expressio
27e80 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
27e90 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  [[SQLITE_LIMIT_C
27ea0 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d  OMPOUND_SELECT]]
27eb0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
27ec0 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c  MIT_COMPOUND_SEL
27ed0 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ECT</dt>.** <dd>
27ee0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
27ef0 65 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61  er of terms in a
27f00 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54   compound SELECT
27f10 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e   statement.</dd>
27f20 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
27f30 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d  E_LIMIT_VDBE_OP]
27f40 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
27f50 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74  IMIT_VDBE_OP</dt
27f60 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
27f70 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69  imum number of i
27f80 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61  nstructions in a
27f90 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65   virtual machine
27fa0 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64   program.** used
27fb0 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e   to implement an
27fc0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
27fd0 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e   This limit is n
27fe0 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20  ot currently.** 
27ff0 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68  enforced, though
28000 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61   that might be a
28010 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74  dded in some fut
28020 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a  ure release of.*
28030 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e  * SQLite.</dd>)^
28040 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
28050 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
28060 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  RG]] ^(<dt>SQLIT
28070 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e  E_LIMIT_FUNCTION
28080 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  _ARG</dt>.** <dd
28090 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
280a0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
280b0 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c   on a function.<
280c0 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
280d0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41  QLITE_LIMIT_ATTA
280e0 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  CHED]] ^(<dt>SQL
280f0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
28100 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  ED</dt>.** <dd>T
28110 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
28120 72 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61  r of [ATTACH | a
28130 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65  ttached database
28140 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  s].)^</dd>.**.**
28150 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28160 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e  LIKE_PATTERN_LEN
28170 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53  GTH]].** ^(<dt>S
28180 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
28190 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c  _PATTERN_LENGTH<
281a0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
281b0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
281c0 66 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72  f the pattern ar
281d0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c  gument to the [L
281e0 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42  IKE] or.** [GLOB
281f0 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64  ] operators.</dd
28200 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
28210 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
28220 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28  E_NUMBER]].** ^(
28230 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
28240 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
28250 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
28260 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e   maximum index n
28270 75 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61  umber of any [pa
28280 72 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53  rameter] in an S
28290 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a  QL statement.)^.
282a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
282b0 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50  IMIT_TRIGGER_DEP
282c0 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
282d0 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
282e0 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
282f0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
28300 70 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e  pth of recursion
28310 20 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f   for triggers.</
28320 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a  dd>)^.** </dl>.*
28330 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
28340 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20  _LIMIT_LENGTH   
28350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
28360 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   0.#define SQLIT
28370 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
28380 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  TH              
28390 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
283a0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20  TE_LIMIT_COLUMN 
283b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
283c0 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
283d0 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44  ITE_LIMIT_EXPR_D
283e0 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
283f0 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
28400 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
28410 55 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20  UND_SELECT      
28420 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
28430 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45  QLITE_LIMIT_VDBE
28440 5f 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20  _OP             
28450 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20        5.#define 
28460 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
28470 43 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20  CTION_ARG       
28480 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65         6.#define
28490 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54   SQLITE_LIMIT_AT
284a0 54 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20  TACHED          
284b0 20 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e          7.#defin
284c0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
284d0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
284e0 54 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69  TH       8.#defi
284f0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
28500 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20  VARIABLE_NUMBER 
28510 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
28520 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
28530 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20  _TRIGGER_DEPTH  
28540 20 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a            10../*
28550 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
28560 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53  mpiling An SQL S
28570 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57  tatement.** KEYW
28580 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65  ORDS: {SQL state
28590 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a  ment compiler}.*
285a0 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20  *.** To execute 
285b0 61 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74  an SQL query, it
285c0 20 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63   must first be c
285d0 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62  ompiled into a b
285e0 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67  yte-code.** prog
285f0 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66  ram using one of
28600 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
28610 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
28620 20 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c   argument, "db",
28630 20 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20   is a [database 
28640 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61  connection] obta
28650 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70  ined from a.** p
28660 72 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20  rior successful 
28670 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
28680 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
28690 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72  e3_open_v2()] or
286a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  .** [sqlite3_ope
286b0 6e 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74  n16()].  The dat
286c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
286d0 20 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62   must not have b
286e0 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a  een closed..**.*
286f0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
28700 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69  ument, "zSql", i
28710 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
28720 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20  to be compiled, 
28730 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69  encoded.** as ei
28740 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
28750 46 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74  F-16.  The sqlit
28760 65 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64  e3_prepare() and
28770 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
28780 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  _v2().** interfa
28790 63 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61  ces use UTF-8, a
287a0 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
287b0 72 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74  re16() and sqlit
287c0 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28  e3_prepare16_v2(
287d0 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e  ).** use UTF-16.
287e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
287f0 42 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73  Byte argument is
28800 20 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c   less than zero,
28810 20 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65   then zSql is re
28820 61 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20  ad up to the.** 
28830 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69  first zero termi
28840 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65  nator. ^If nByte
28850 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
28860 2c 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65  , then it is the
28870 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62   maximum.** numb
28880 65 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61  er of  bytes rea
28890 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57  d from zSql.  ^W
288a0 68 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e  hen nByte is non
288b0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a  -negative, the.*
288c0 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e  * zSql string en
288d0 64 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65  ds at either the
288e0 20 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72   first '\000' or
288f0 20 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63   '\u0000' charac
28900 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42  ter or.** the nB
28910 79 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69  yte-th byte, whi
28920 63 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72  chever comes fir
28930 73 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65  st. If the calle
28940 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20  r knows.** that 
28950 74 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72  the supplied str
28960 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69  ing is nul-termi
28970 6e 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72  nated, then ther
28980 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20  e is a small.** 
28990 70 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61  performance adva
289a0 6e 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e  ntage to be gain
289b0 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e  ed by passing an
289c0 20 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72   nByte parameter
289d0 20 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61   that.** is equa
289e0 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20  l to the number 
289f0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20  of bytes in the 
28a00 69 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e  input string <i>
28a10 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a  including</i>.**
28a20 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61   the nul-termina
28a30 74 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69  tor bytes as thi
28a40 73 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66  s saves SQLite f
28a50 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a  rom having to.**
28a60 20 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20   make a copy of 
28a70 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
28a80 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61  ..**.** ^If pzTa
28a90 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  il is not NULL t
28aa0 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d  hen *pzTail is m
28ab0 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
28ac0 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a  the first byte.*
28ad0 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f  * past the end o
28ae0 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20  f the first SQL 
28af0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
28b00 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  l.  These routin
28b10 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69  es only.** compi
28b20 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61  le the first sta
28b30 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20  tement in zSql, 
28b40 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65  so *pzTail is le
28b50 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a  ft pointing to.*
28b60 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75  * what remains u
28b70 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  ncompiled..**.**
28b80 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66   ^*ppStmt is lef
28b90 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20  t pointing to a 
28ba0 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72  compiled [prepar
28bb0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
28bc0 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65  at can be.** exe
28bd0 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cuted using [sql
28be0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e  ite3_step()].  ^
28bf0 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65  If there is an e
28c00 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73  rror, *ppStmt is
28c10 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e   set.** to NULL.
28c20 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20    ^If the input 
28c30 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f  text contains no
28c40 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70   SQL (if the inp
28c50 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a  ut is an empty.*
28c60 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f  * string or a co
28c70 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53  mment) then *ppS
28c80 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55  tmt is set to NU
28c90 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69  LL..** The calli
28ca0 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20  ng procedure is 
28cb0 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
28cc0 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d  deleting the com
28cd0 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61  piled.** SQL sta
28ce0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
28cf0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
28d00 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66  ] after it has f
28d10 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e  inished with it.
28d20 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e  .** ppStmt may n
28d30 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ot be NULL..**.*
28d40 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74  * ^On success, t
28d50 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
28d60 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72  re() family of r
28d70 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
28d80 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f  SQLITE_OK];.** o
28d90 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72  therwise an [err
28da0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
28db0 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rned..**.** The 
28dc0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28dd0 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  v2() and sqlite3
28de0 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20  _prepare16_v2() 
28df0 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a  interfaces are.*
28e00 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f  * recommended fo
28e10 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61  r all new progra
28e20 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65  ms. The two olde
28e30 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  r interfaces are
28e40 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72   retained.** for
28e50 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
28e60 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68  tibility, but th
28e70 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f  eir use is disco
28e80 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74  uraged..** ^In t
28e90 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
28ea0 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64  es, the prepared
28eb0 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68   statement.** th
28ec0 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28  at is returned (
28ed0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
28ee0 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61  t] object) conta
28ef0 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68  ins a copy of th
28f00 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51  e.** original SQ
28f10 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75  L text. This cau
28f20 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ses the [sqlite3
28f30 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61  _step()] interfa
28f40 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20  ce to.** behave 
28f50 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74  differently in t
28f60 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a  hree ways:.**.**
28f70 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a   <ol>.** <li>.**
28f80 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73   ^If the databas
28f90 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73  e schema changes
28fa0 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74  , instead of ret
28fb0 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53  urning [SQLITE_S
28fc0 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20  CHEMA] as it.** 
28fd0 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64  always used to d
28fe0 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  o, [sqlite3_step
28ff0 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74  ()] will automat
29000 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65  ically recompile
29010 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74   the SQL.** stat
29020 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f  ement and try to
29030 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a 2a   run it again..*
29040 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
29050 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65  i>.** ^When an e
29060 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71  rror occurs, [sq
29070 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
29080 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66  ll return one of
29090 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a   the detailed.**
290a0 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f   [error codes] o
290b0 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f  r [extended erro
290c0 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20  r codes].  ^The 
290d0 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20  legacy behavior 
290e0 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c  was that.** [sql
290f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75  ite3_step()] wou
29100 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61  ld only return a
29110 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45   generic [SQLITE
29120 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63  _ERROR] result c
29130 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61  ode.** and the a
29140 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64  pplication would
29150 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20   have to make a 
29160 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b  second call to [
29170 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29180 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  .** in order to 
29190 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79  find the underly
291a0 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65  ing cause of the
291b0 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74   problem. With t
291c0 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a  he "v2" prepare.
291d0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74  ** interfaces, t
291e0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65  he underlying re
291f0 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72  ason for the err
29200 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  or is returned i
29210 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c  mmediately..** <
29220 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a  /li>.**.** <li>.
29230 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69  ** ^If the speci
29240 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20  fic value bound 
29250 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20  to [parameter | 
29260 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20  host parameter] 
29270 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45  in the .** WHERE
29280 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e   clause might in
29290 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69  fluence the choi
292a0 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e  ce of query plan
292b0 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74   for a statement
292c0 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74  ,.** then the st
292d0 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  atement will be 
292e0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65  automatically re
292f0 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20  compiled, as if 
29300 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a  there had been .
29310 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e  ** a schema chan
29320 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74  ge, on the first
29330 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28    [sqlite3_step(
29340 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e  )] call followin
29350 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20  g any change.** 
29360 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  to the [sqlite3_
29370 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64  bind_text | bind
29380 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70  ings] of that [p
29390 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e  arameter]. .** ^
293a0 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c  The specific val
293b0 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75  ue of WHERE-clau
293c0 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d  se [parameter] m
293d0 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74  ight influence t
293e0 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66  he .** choice of
293f0 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74   query plan if t
29400 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
29410 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69  the left-hand si
29420 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a  de of a [LIKE].*
29430 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  * or [GLOB] oper
29440 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70  ator or if the p
29450 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70  arameter is comp
29460 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78  ared to an index
29470 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64  ed column.** and
29480 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41   the [SQLITE_ENA
29490 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69  BLE_STAT3] compi
294a0 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
294b0 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74 68  s enabled..** th
294c0 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20 3c  e .** </li>.** <
294d0 2f 6f 6c 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  /ol>.*/.SQLITE_A
294e0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
294f0 72 65 70 61 72 65 28 0a 20 20 73 71 6c 69 74 65  repare(.  sqlite
29500 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
29510 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
29520 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
29530 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20  char *zSql,     
29540 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
29550 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  nt, UTF-8 encode
29560 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65  d */.  int nByte
29570 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
29580 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  * Maximum length
29590 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65   of zSql in byte
295a0 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f  s. */.  sqlite3_
295b0 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20  stmt **ppStmt,  
295c0 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e  /* OUT: Statemen
295d0 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  t handle */.  co
295e0 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69  nst char **pzTai
295f0 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f  l     /* OUT: Po
29600 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20  inter to unused 
29610 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20  portion of zSql 
29620 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
29630 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65   int sqlite3_pre
29640 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74  pare_v2(.  sqlit
29650 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
29660 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
29670 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
29680 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20   char *zSql,    
29690 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
296a0 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64  ent, UTF-8 encod
296b0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
296c0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
296d0 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
296e0 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
296f0 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
29700 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
29710 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
29720 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
29730 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61  onst char **pzTa
29740 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
29750 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
29760 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
29770 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50   */.);.SQLITE_AP
29780 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  I int sqlite3_pr
29790 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
297a0 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
297b0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
297c0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
297d0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
297e0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
297f0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
29800 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
29810 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
29820 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
29830 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
29840 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
29850 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
29860 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
29870 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
29880 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
29890 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
298a0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
298b0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
298c0 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41  l */.);.SQLITE_A
298d0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  PI int sqlite3_p
298e0 72 65 70 61 72 65 31 36 5f 76 32 28 0a 20 20 73  repare16_v2(.  s
298f0 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
29900 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
29910 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  se handle */.  c
29920 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c  onst void *zSql,
29930 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74         /* SQL st
29940 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20  atement, UTF-16 
29950 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
29960 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
29970 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
29980 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
29990 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
299a0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
299b0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
299c0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
299d0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
299e0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
299f0 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
29a00 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
29a10 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a   zSql */.);../*.
29a20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 74  ** CAPI3REF: Ret
29a30 72 69 65 76 69 6e 67 20 53 74 61 74 65 6d 65 6e  rieving Statemen
29a40 74 20 53 51 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  t SQL.**.** ^Thi
29a50 73 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20  s interface can 
29a60 62 65 20 75 73 65 64 20 74 6f 20 72 65 74 72 69  be used to retri
29a70 65 76 65 20 61 20 73 61 76 65 64 20 63 6f 70 79  eve a saved copy
29a80 20 6f 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   of the original
29a90 0a 2a 2a 20 53 51 4c 20 74 65 78 74 20 75 73 65  .** SQL text use
29aa0 64 20 74 6f 20 63 72 65 61 74 65 20 61 20 5b 70  d to create a [p
29ab0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
29ac0 74 5d 20 69 66 20 74 68 61 74 20 73 74 61 74 65  t] if that state
29ad0 6d 65 6e 74 20 77 61 73 0a 2a 2a 20 63 6f 6d 70  ment was.** comp
29ae0 69 6c 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  iled using eithe
29af0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
29b00 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c  re_v2()] or [sql
29b10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
29b20 32 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  2()]..*/.SQLITE_
29b30 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
29b40 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
29b50 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
29b60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29b70 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
29b80 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
29b90 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
29ba0 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  base.**.** ^The 
29bb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
29bc0 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
29bd0 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
29be0 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
29bf0 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
29c00 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29c10 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
29c20 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
29c30 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
29c40 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
29c50 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
29c60 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
29c70 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
29c80 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
29c90 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
29ca0 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
29cb0 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
29cc0 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
29cd0 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
29ce0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
29cf0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
29d00 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
29d10 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
29d20 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
29d30 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
29d40 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
29d50 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
29d60 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
29d70 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
29d80 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
29d90 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
29da0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
29db0 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
29dc0 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
29dd0 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
29de0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
29df0 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
29e00 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
29e10 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
29e20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
29e30 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
29e40 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
29e50 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
29e60 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
29e70 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
29e80 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
29e90 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
29ea0 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
29eb0 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
29ec0 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
29ed0 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
29ee0 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
29ef0 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
29f00 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
29f10 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
29f20 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
29f30 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
29f40 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
29f50 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
29f60 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
29f70 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
29f80 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
29f90 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
29fa0 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
29fb0 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
29fc0 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
29fd0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
29fe0 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
29ff0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
2a000 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
2a010 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
2a020 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
2a030 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
2a040 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
2a050 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2a060 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
2a070 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
2a080 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
2a090 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
2a0a0 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
2a0b0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
2a0c0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
2a0d0 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
2a0e0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
2a0f0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2a100 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
2a110 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2a120 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
2a130 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2a140 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
2a150 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
2a160 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
2a170 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
2a180 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2a190 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
2a1a0 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
2a1b0 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
2a1c0 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
2a1d0 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f  t has not run to
2a1e0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f   completion and/
2a1f0 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62  or has not .** b
2a200 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
2a210 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
2a220 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
2a230 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
2a240 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
2a250 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
2a260 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2a270 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
2a280 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
2a290 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
2a2a0 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
2a2b0 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
2a2c0 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
2a2d0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
2a2e0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
2a2f0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
2a300 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
2a310 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
2a320 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
2a330 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
2a340 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
2a350 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
2a360 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
2a370 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
2a380 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
2a390 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
2a3a0 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
2a3b0 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
2a3c0 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
2a3d0 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
2a3e0 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
2a3f0 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
2a400 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
2a410 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
2a420 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
2a430 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
2a440 6f 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  open..*/.SQLITE_
2a450 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2a460 73 74 6d 74 5f 62 75 73 79 28 73 71 6c 69 74 65  stmt_busy(sqlite
2a470 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2a480 20 43 41 50 49 33 52 45 46 3a 20 44 79 6e 61 6d   CAPI3REF: Dynam
2a490 69 63 61 6c 6c 79 20 54 79 70 65 64 20 56 61 6c  ically Typed Val
2a4a0 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59  ue Object.** KEY
2a4b0 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65 63 74 65  WORDS: {protecte
2a4c0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d  d sqlite3_value}
2a4d0 20 7b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   {unprotected sq
2a4e0 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a 2a 2a 0a  lite3_value}.**.
2a4f0 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 74  ** SQLite uses t
2a500 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2a510 20 6f 62 6a 65 63 74 20 74 6f 20 72 65 70 72 65   object to repre
2a520 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75 65 73 0a  sent all values.
2a530 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 73  ** that can be s
2a540 74 6f 72 65 64 20 69 6e 20 61 20 64 61 74 61 62  tored in a datab
2a550 61 73 65 20 74 61 62 6c 65 2e 20 53 51 4c 69 74  ase table. SQLit
2a560 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 74  e uses dynamic t
2a570 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20 74 68 65  yping.** for the
2a580 20 76 61 6c 75 65 73 20 69 74 20 73 74 6f 72 65   values it store
2a590 73 2e 20 20 5e 56 61 6c 75 65 73 20 73 74 6f 72  s.  ^Values stor
2a5a0 65 64 20 69 6e 20 73 71 6c 69 74 65 33 5f 76 61  ed in sqlite3_va
2a5b0 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a 2a 20 63  lue objects.** c
2a5c0 61 6e 20 62 65 20 69 6e 74 65 67 65 72 73 2c 20  an be integers, 
2a5d0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
2a5e0 61 6c 75 65 73 2c 20 73 74 72 69 6e 67 73 2c 20  alues, strings, 
2a5f0 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c 4c 2e 0a  BLOBs, or NULL..
2a600 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69 74 65 33  **.** An sqlite3
2a610 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 6d 61  _value object ma
2a620 79 20 62 65 20 65 69 74 68 65 72 20 22 70 72 6f  y be either "pro
2a630 74 65 63 74 65 64 22 20 6f 72 20 22 75 6e 70 72  tected" or "unpr
2a640 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20 53 6f 6d  otected"..** Som
2a650 65 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  e interfaces req
2a660 75 69 72 65 20 61 20 70 72 6f 74 65 63 74 65 64  uire a protected
2a670 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 20   sqlite3_value. 
2a680 20 4f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   Other interface
2a690 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63 65 70 74  s.** will accept
2a6a0 20 65 69 74 68 65 72 20 61 20 70 72 6f 74 65 63   either a protec
2a6b0 74 65 64 20 6f 72 20 61 6e 20 75 6e 70 72 6f 74  ted or an unprot
2a6c0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
2a6d0 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79 20 69 6e  lue..** Every in
2a6e0 74 65 72 66 61 63 65 20 74 68 61 74 20 61 63 63  terface that acc
2a6f0 65 70 74 73 20 73 71 6c 69 74 65 33 5f 76 61 6c  epts sqlite3_val
2a700 75 65 20 61 72 67 75 6d 65 6e 74 73 20 73 70 65  ue arguments spe
2a710 63 69 66 69 65 73 0a 2a 2a 20 77 68 65 74 68 65  cifies.** whethe
2a720 72 20 6f 72 20 6e 6f 74 20 69 74 20 72 65 71 75  r or not it requ
2a730 69 72 65 73 20 61 20 70 72 6f 74 65 63 74 65 64  ires a protected
2a740 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a   sqlite3_value..
2a750 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72 6d 73 20  **.** The terms 
2a760 22 70 72 6f 74 65 63 74 65 64 22 20 61 6e 64 20  "protected" and 
2a770 22 75 6e 70 72 6f 74 65 63 74 65 64 22 20 72 65  "unprotected" re
2a780 66 65 72 20 74 6f 20 77 68 65 74 68 65 72 20 6f  fer to whether o
2a790 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75 74 65 78  r not.** a mutex
2a7a0 20 69 73 20 68 65 6c 64 2e 20 20 41 6e 20 69 6e   is held.  An in
2a7b0 74 65 72 6e 61 6c 20 6d 75 74 65 78 20 69 73 20  ternal mutex is 
2a7c0 68 65 6c 64 20 66 6f 72 20 61 20 70 72 6f 74 65  held for a prote
2a7d0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2a7e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 62 75 74  value object but
2a7f0 20 6e 6f 20 6d 75 74 65 78 20 69 73 20 68 65 6c   no mutex is hel
2a800 64 20 66 6f 72 20 61 6e 20 75 6e 70 72 6f 74 65  d for an unprote
2a810 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
2a820 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e 20 20 49  value object.  I
2a830 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
2a840 69 6c 65 64 20 74 6f 20 62 65 20 73 69 6e 67 6c  iled to be singl
2a850 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 28 77  e-threaded.** (w
2a860 69 74 68 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  ith [SQLITE_THRE
2a870 41 44 53 41 46 45 3d 30 5d 20 61 6e 64 20 77 69  ADSAFE=0] and wi
2a880 74 68 20 5b 73 71 6c 69 74 65 33 5f 74 68 72 65  th [sqlite3_thre
2a890 61 64 73 61 66 65 28 29 5d 20 72 65 74 75 72 6e  adsafe()] return
2a8a0 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20 69 66 20  ing 0).** or if 
2a8b0 53 51 4c 69 74 65 20 69 73 20 72 75 6e 20 69 6e  SQLite is run in
2a8c0 20 6f 6e 65 20 6f 66 20 72 65 64 75 63 65 64 20   one of reduced 
2a8d0 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a 2a 2a 20  mutex modes .** 
2a8e0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
2a8f0 49 4e 47 4c 45 54 48 52 45 41 44 5d 20 6f 72 20  INGLETHREAD] or 
2a900 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
2a910 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a 2a 20 74  ULTITHREAD].** t
2a920 68 65 6e 20 74 68 65 72 65 20 69 73 20 6e 6f 20  hen there is no 
2a930 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
2a940 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
2a950 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
2a960 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2a970 62 6a 65 63 74 73 20 61 6e 64 20 74 68 65 79 20  bjects and they 
2a980 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 74 65  can be used inte
2a990 72 63 68 61 6e 67 65 61 62 6c 79 2e 20 20 48 6f  rchangeably.  Ho
2a9a0 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72 20 6d 61  wever,.** for ma
2a9b0 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f 72 74 61  ximum code porta
2a9c0 62 69 6c 69 74 79 20 69 74 20 69 73 20 72 65 63  bility it is rec
2a9d0 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70  ommended that ap
2a9e0 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 74  plications.** st
2a9f0 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20 64 69 73  ill make the dis
2aa00 74 69 6e 63 74 69 6f 6e 20 62 65 74 77 65 65 6e  tinction between
2aa10 20 70 72 6f 74 65 63 74 65 64 20 61 6e 64 20 75   protected and u
2aa20 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2aa30 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2aa40 63 74 73 20 65 76 65 6e 20 77 68 65 6e 20 6e 6f  cts even when no
2aa50 74 20 73 74 72 69 63 74 6c 79 20 72 65 71 75 69  t strictly requi
2aa60 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  red..**.** ^The 
2aa70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2aa80 6a 65 63 74 73 20 74 68 61 74 20 61 72 65 20 70  jects that are p
2aa90 61 73 73 65 64 20 61 73 20 70 61 72 61 6d 65 74  assed as paramet
2aaa0 65 72 73 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ers into the.** 
2aab0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2aac0 66 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  f [application-d
2aad0 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
2aae0 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f 74 65 63  ions] are protec
2aaf0 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ted..** ^The sql
2ab00 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
2ab10 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2ab20 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ab30 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 6e 70  _value()] is unp
2ab40 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 55 6e 70  rotected..** Unp
2ab50 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2ab60 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 6d  _value objects m
2ab70 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20  ay only be used 
2ab80 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  with.** [sqlite3
2ab90 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 5d  _result_value()]
2aba0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69   and [sqlite3_bi
2abb0 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  nd_value()]..** 
2abc0 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  The [sqlite3_val
2abd0 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65  ue_blob | sqlite
2abe0 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 29 5d 20  3_value_type()] 
2abf0 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 69 6e 74  family of.** int
2ac00 65 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20  erfaces require 
2ac10 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ac20 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 2e  3_value objects.
2ac30 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
2ac40 63 74 20 4d 65 6d 20 73 71 6c 69 74 65 33 5f 76  ct Mem sqlite3_v
2ac50 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  alue;../*.** CAP
2ac60 49 33 52 45 46 3a 20 53 51 4c 20 46 75 6e 63 74  I3REF: SQL Funct
2ac70 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f 62 6a 65  ion Context Obje
2ac80 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 6e  ct.**.** The con
2ac90 74 65 78 74 20 69 6e 20 77 68 69 63 68 20 61 6e  text in which an
2aca0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 65 78   SQL function ex
2acb0 65 63 75 74 65 73 20 69 73 20 73 74 6f 72 65 64  ecutes is stored
2acc0 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74 65   in an.** sqlite
2acd0 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2ace0 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72 20 74 6f  .  ^A pointer to
2acf0 20 61 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74   an sqlite3_cont
2ad00 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a 20 69 73  ext object.** is
2ad10 20 61 6c 77 61 79 73 20 66 69 72 73 74 20 70 61   always first pa
2ad20 72 61 6d 65 74 65 72 20 74 6f 20 5b 61 70 70 6c  rameter to [appl
2ad30 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2ad40 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  SQL functions]..
2ad50 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
2ad60 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
2ad70 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2ad80 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70 61 73 73  tation will pass
2ad90 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e 74 65 72   this.** pointer
2ada0 20 74 68 72 6f 75 67 68 20 69 6e 74 6f 20 63 61   through into ca
2adb0 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2adc0 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20 73 71 6c  result_int | sql
2add0 69 74 65 33 5f 72 65 73 75 6c 74 28 29 5d 2c 0a  ite3_result()],.
2ade0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61 67 67 72  ** [sqlite3_aggr
2adf0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 5d  egate_context()]
2ae00 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  , [sqlite3_user_
2ae10 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  data()],.** [sql
2ae20 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2ae30 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73 71 6c 69  handle()], [sqli
2ae40 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28  te3_get_auxdata(
2ae50 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72 20 5b 73  )],.** and/or [s
2ae60 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
2ae70 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  ta()]..*/.typede
2ae80 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
2ae90 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69 74 65 33  _context sqlite3
2aea0 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a 0a 2a 2a  _context;../*.**
2aeb0 20 43 41 50 49 33 52 45 46 3a 20 42 69 6e 64 69   CAPI3REF: Bindi
2aec0 6e 67 20 56 61 6c 75 65 73 20 54 6f 20 50 72 65  ng Values To Pre
2aed0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 73  pared Statements
2aee0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 68  .** KEYWORDS: {h
2aef0 6f 73 74 20 70 61 72 61 6d 65 74 65 72 7d 20 7b  ost parameter} {
2af00 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 7d  host parameters}
2af10 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
2af20 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59 57 4f 52   name}.** KEYWOR
2af30 44 53 3a 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  DS: {SQL paramet
2af40 65 72 7d 20 7b 53 51 4c 20 70 61 72 61 6d 65 74  er} {SQL paramet
2af50 65 72 73 7d 20 7b 70 61 72 61 6d 65 74 65 72 20  ers} {parameter 
2af60 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a 2a 20 5e  binding}.**.** ^
2af70 28 49 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74  (In the SQL stat
2af80 65 6d 65 6e 74 20 74 65 78 74 20 69 6e 70 75 74  ement text input
2af90 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   to [sqlite3_pre
2afa0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 69  pare_v2()] and i
2afb0 74 73 20 76 61 72 69 61 6e 74 73 2c 0a 2a 2a 20  ts variants,.** 
2afc0 6c 69 74 65 72 61 6c 73 20 6d 61 79 20 62 65 20  literals may be 
2afd0 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 5b 70  replaced by a [p
2afe0 61 72 61 6d 65 74 65 72 5d 20 74 68 61 74 20 6d  arameter] that m
2aff0 61 74 63 68 65 73 20 6f 6e 65 20 6f 66 20 66 6f  atches one of fo
2b000 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65 6d 70 6c  llowing.** templ
2b010 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  ates:.**.** <ul>
2b020 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a 2a 20 3c  .** <li>  ?.** <
2b030 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20 3c 6c 69  li>  ?NNN.** <li
2b040 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20  >  :VVV.** <li> 
2b050 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e 20 20 24   @VVV.** <li>  $
2b060 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a  VVV.** </ul>.**.
2b070 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d 70 6c 61  ** In the templa
2b080 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e 4e 20 72  tes above, NNN r
2b090 65 70 72 65 73 65 6e 74 73 20 61 6e 20 69 6e 74  epresents an int
2b0a0 65 67 65 72 20 6c 69 74 65 72 61 6c 2c 0a 2a 2a  eger literal,.**
2b0b0 20 61 6e 64 20 56 56 56 20 72 65 70 72 65 73 65   and VVV represe
2b0c0 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e 75 6d 65  nts an alphanume
2b0d0 72 69 63 20 69 64 65 6e 74 69 66 69 65 72 2e 29  ric identifier.)
2b0e0 5e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 6f  ^  ^The values o
2b0f0 66 20 74 68 65 73 65 0a 2a 2a 20 70 61 72 61 6d  f these.** param
2b100 65 74 65 72 73 20 28 61 6c 73 6f 20 63 61 6c 6c  eters (also call
2b110 65 64 20 22 68 6f 73 74 20 70 61 72 61 6d 65 74  ed "host paramet
2b120 65 72 20 6e 61 6d 65 73 22 20 6f 72 20 22 53 51  er names" or "SQ
2b130 4c 20 70 61 72 61 6d 65 74 65 72 73 22 29 0a 2a  L parameters").*
2b140 2a 20 63 61 6e 20 62 65 20 73 65 74 20 75 73 69  * can be set usi
2b150 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
2b160 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2b170 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 0a 2a   defined here..*
2b180 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2b190 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
2b1a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
2b1b0 20 72 6f 75 74 69 6e 65 73 20 69 73 20 61 6c 77   routines is alw
2b1c0 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72  ays.** a pointer
2b1d0 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
2b1e0 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 20 72 65  _stmt] object re
2b1f0 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 5b  turned from.** [
2b200 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
2b210 76 32 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  v2()] or its var
2b220 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  iants..**.** ^Th
2b230 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2b240 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2b250 66 20 74 68 65 20 53 51 4c 20 70 61 72 61 6d 65  f the SQL parame
2b260 74 65 72 20 74 6f 20 62 65 20 73 65 74 2e 0a 2a  ter to be set..*
2b270 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  * ^The leftmost 
2b280 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 68 61  SQL parameter ha
2b290 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2e  s an index of 1.
2b2a0 20 20 5e 57 68 65 6e 20 74 68 65 20 73 61 6d 65    ^When the same
2b2b0 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c 20 70 61   named.** SQL pa
2b2c0 72 61 6d 65 74 65 72 20 69 73 20 75 73 65 64 20  rameter is used 
2b2d0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 2c 20  more than once, 
2b2e0 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2b2f0 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75 72 72 65  quent.** occurre
2b300 6e 63 65 73 20 68 61 76 65 20 74 68 65 20 73 61  nces have the sa
2b310 6d 65 20 69 6e 64 65 78 20 61 73 20 74 68 65 20  me index as the 
2b320 66 69 72 73 74 20 6f 63 63 75 72 72 65 6e 63 65  first occurrence
2b330 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64 65 78 20  ..** ^The index 
2b340 66 6f 72 20 6e 61 6d 65 64 20 70 61 72 61 6d 65  for named parame
2b350 74 65 72 73 20 63 61 6e 20 62 65 20 6c 6f 6f 6b  ters can be look
2b360 65 64 20 75 70 20 75 73 69 6e 67 20 74 68 65 0a  ed up using the.
2b370 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
2b380 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2b390 28 29 5d 20 41 50 49 20 69 66 20 64 65 73 69 72  ()] API if desir
2b3a0 65 64 2e 20 20 5e 54 68 65 20 69 6e 64 65 78 0a  ed.  ^The index.
2b3b0 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22 20 70 61  ** for "?NNN" pa
2b3c0 72 61 6d 65 74 65 72 73 20 69 73 20 74 68 65 20  rameters is the 
2b3d0 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e 0a 2a 2a  value of NNN..**
2b3e0 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c 75 65 20   ^The NNN value 
2b3f0 6d 75 73 74 20 62 65 20 62 65 74 77 65 65 6e 20  must be between 
2b400 31 20 61 6e 64 20 74 68 65 20 5b 73 71 6c 69 74  1 and the [sqlit
2b410 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 70  e3_limit()].** p
2b420 61 72 61 6d 65 74 65 72 20 5b 53 51 4c 49 54 45  arameter [SQLITE
2b430 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
2b440 4e 55 4d 42 45 52 5d 20 28 64 65 66 61 75 6c 74  NUMBER] (default
2b450 20 76 61 6c 75 65 3a 20 39 39 39 29 2e 0a 2a 2a   value: 999)..**
2b460 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20 61  .** ^The third a
2b470 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 76  rgument is the v
2b480 61 6c 75 65 20 74 6f 20 62 69 6e 64 20 74 6f 20  alue to bind to 
2b490 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  the parameter..*
2b4a0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
2b4b0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
2b4c0 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
2b4d0 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
2b4e0 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
2b4f0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
2b500 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
2b510 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
2b520 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
2b530 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
2b540 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
2b550 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
2b560 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2b570 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
2b580 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
2b590 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
2b5a0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
2b5b0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
2b5c0 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
2b5d0 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
2b5e0 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
2b5f0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2b600 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
2b610 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
2b620 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
2b630 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
2b640 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
2b650 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
2b660 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
2b670 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
2b680 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
2b690 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
2b6a0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
2b6b0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
2b6c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2b6d0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
2b6e0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74  _bind_text16() t
2b6f0 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74  hen that paramet
2b700 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
2b710 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
2b720 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
2b730 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
2b740 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
2b750 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
2b760 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
2b770 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
2b780 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
2b790 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
2b7a0 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
2b7b0 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
2b7c0 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
2b7d0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
2b7e0 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
2b7f0 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
2b800 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
2b810 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
2b820 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
2b830 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
2b840 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
2b850 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2b860 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
2b870 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
2b880 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
2b890 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
2b8a0 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
2b8b0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
2b8c0 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
2b8d0 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
2b8e0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
2b8f0 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
2b900 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
2b910 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
2b920 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
2b930 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
2b940 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
2b950 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
2b960 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73  if the call to s
2b970 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2b980 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  (),.** sqlite3_b
2b990 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73  ind_text(), or s
2b9a0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2b9b0 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a  16() fails.  .**
2b9c0 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
2b9d0 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
2b9e0 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
2b9f0 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
2ba00 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
2ba10 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
2ba20 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2ba30 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
2ba40 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
2ba50 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
2ba60 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
2ba70 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
2ba80 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
2ba90 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
2baa0 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
2bab0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
2bac0 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
2bad0 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
2bae0 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
2baf0 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
2bb00 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
2bb10 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
2bb20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2bb30 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
2bb40 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
2bb50 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
2bb60 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
2bb70 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
2bb80 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
2bb90 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
2bba0 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
2bbb0 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
2bbc0 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
2bbd0 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
2bbe0 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
2bbf0 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
2bc00 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
2bc10 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
2bc20 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
2bc30 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
2bc40 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
2bc50 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
2bc60 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
2bc70 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
2bc80 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
2bc90 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
2bca0 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
2bcb0 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
2bcc0 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
2bcd0 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
2bce0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
2bcf0 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
2bd00 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
2bd10 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
2bd20 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2bd30 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
2bd40 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
2bd50 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
2bd60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
2bd70 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
2bd80 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
2bd90 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
2bda0 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
2bdb0 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
2bdc0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
2bdd0 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
2bde0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
2bdf0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
2be00 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
2be10 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2be20 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
2be30 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
2be40 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
2be50 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
2be60 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
2be70 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
2be80 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
2be90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2bea0 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
2beb0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
2bec0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
2bed0 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
2bee0 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
2bef0 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
2bf00 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
2bf10 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
2bf20 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
2bf30 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
2bf40 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
2bf50 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
2bf60 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
2bf70 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
2bf80 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
2bf90 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
2bfa0 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
2bfb0 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
2bfc0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2bfd0 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2bfe0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2bff0 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
2c000 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2c010 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
2c020 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2c030 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
2c040 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2c050 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2c060 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
2c070 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
2c080 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2c090 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2c0a0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2c0b0 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73 71  3_bind_double(sq
2c0c0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c0d0 2c 20 64 6f 75 62 6c 65 29 3b 0a 53 51 4c 49 54  , double);.SQLIT
2c0e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2c0f0 33 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74  3_bind_int(sqlit
2c100 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
2c110 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2c120 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2c130 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
2c140 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
2c150 65 33 5f 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54  e3_int64);.SQLIT
2c160 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2c170 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
2c180 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
2c190 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2c1a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2c1b0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
2c1c0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72   int, const char
2c1d0 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
2c1e0 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2c1f0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2c200 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
2c210 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2c220 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2c230 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2c240 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  *));.SQLITE_API 
2c250 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2c260 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2c270 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
2c280 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29   sqlite3_value*)
2c290 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
2c2a0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
2c2b0 72 6f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  roblob(sqlite3_s
2c2c0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e  tmt*, int, int n
2c2d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2c2e0 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 53 51  EF: Number Of SQ
2c2f0 4c 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  L Parameters.**.
2c300 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
2c310 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2c320 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
2c330 6f 66 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  of [SQL paramete
2c340 72 73 5d 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65  rs].** in a [pre
2c350 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c360 2e 20 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  .  SQL parameter
2c370 73 20 61 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20  s are tokens of 
2c380 74 68 65 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c  the.** form "?",
2c390 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c   "?NNN", ":AAA",
2c3a0 20 22 24 41 41 41 22 2c 20 6f 72 20 22 40 41 41   "$AAA", or "@AA
2c3b0 41 22 20 74 68 61 74 20 73 65 72 76 65 20 61 73  A" that serve as
2c3c0 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c 64 65 72 73  .** placeholders
2c3d0 20 66 6f 72 20 76 61 6c 75 65 73 20 74 68 61 74   for values that
2c3e0 20 61 72 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   are [sqlite3_bi
2c3f0 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d  nd_blob | bound]
2c400 0a 2a 2a 20 74 6f 20 74 68 65 20 70 61 72 61 6d  .** to the param
2c410 65 74 65 72 73 20 61 74 20 61 20 6c 61 74 65 72  eters at a later
2c420 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54   time..**.** ^(T
2c430 68 69 73 20 72 6f 75 74 69 6e 65 20 61 63 74 75  his routine actu
2c440 61 6c 6c 79 20 72 65 74 75 72 6e 73 20 74 68 65  ally returns the
2c450 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 6c 61   index of the la
2c460 72 67 65 73 74 20 28 72 69 67 68 74 6d 6f 73 74  rgest (rightmost
2c470 29 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e 20  ).** parameter. 
2c480 46 6f 72 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78  For all forms ex
2c490 63 65 70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20  cept ?NNN, this 
2c4a0 77 69 6c 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20  will correspond 
2c4b0 74 6f 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  to the.** number
2c4c0 20 6f 66 20 75 6e 69 71 75 65 20 70 61 72 61 6d   of unique param
2c4d0 65 74 65 72 73 2e 20 20 49 66 20 70 61 72 61 6d  eters.  If param
2c4e0 65 74 65 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e  eters of the ?NN
2c4f0 4e 20 66 6f 72 6d 20 61 72 65 20 75 73 65 64 2c  N form are used,
2c500 0a 2a 2a 20 74 68 65 72 65 20 6d 61 79 20 62 65  .** there may be
2c510 20 67 61 70 73 20 69 6e 20 74 68 65 20 6c 69 73   gaps in the lis
2c520 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  t.)^.**.** See a
2c530 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2c540 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2c550 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2c560 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2c570 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64  ter_name()], and
2c580 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2c590 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
2c5a0 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  x()]..*/.SQLITE_
2c5b0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2c5c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
2c5d0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2c5e0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2c5f0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
2c600 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
2c610 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c620 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2c630 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
2c640 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
2c650 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2c660 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
2c670 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
2c680 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2c690 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
2c6a0 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
2c6b0 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
2c6c0 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
2c6d0 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
2c6e0 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
2c6f0 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
2c700 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
2c710 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
2c720 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
2c730 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
2c740 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
2c750 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
2c760 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
2c770 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
2c780 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
2c790 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
2c7a0 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
2c7b0 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
2c7c0 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
2c7d0 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
2c7e0 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
2c7f0 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
2c800 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
2c810 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
2c820 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
2c830 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
2c840 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
2c850 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2c860 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
2c870 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
2c880 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
2c890 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
2c8a0 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
2c8b0 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
2c8c0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
2c8d0 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
2c8e0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
2c8f0 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
2c900 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
2c910 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
2c920 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
2c930 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
2c940 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
2c950 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2c960 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
2c970 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2c980 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
2c990 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
2c9a0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2c9b0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
2c9c0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2c9d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2c9e0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c  index()]..*/.SQL
2c9f0 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2ca00 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69 6e 64  ar *sqlite3_bind
2ca10 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
2ca20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ca30 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
2ca40 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66 20 41  3REF: Index Of A
2ca50 20 50 61 72 61 6d 65 74 65 72 20 57 69 74 68 20   Parameter With 
2ca60 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a 2a 0a  A Given Name.**.
2ca70 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65 20 69  ** ^Return the i
2ca80 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c 20 70  ndex of an SQL p
2ca90 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e 20 69  arameter given i
2caa0 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65 0a 2a  ts name.  ^The.*
2cab0 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20 72 65  * index value re
2cac0 74 75 72 6e 65 64 20 69 73 20 73 75 69 74 61 62  turned is suitab
2cad0 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20 74 68  le for use as th
2cae0 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61 72 61  e second.** para
2caf0 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65  meter to [sqlite
2cb00 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2cb10 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20 5e 41  te3_bind()].  ^A
2cb20 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65 74 75   zero.** is retu
2cb30 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74 63 68  rned if no match
2cb40 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  ing parameter is
2cb50 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20 70 61   found.  ^The pa
2cb60 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d 65 20  rameter.** name 
2cb70 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20 69 6e  must be given in
2cb80 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66 20 74   UTF-8 even if t
2cb90 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74  he original stat
2cba0 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70 72 65  ement.** was pre
2cbb0 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46 2d 31  pared from UTF-1
2cbc0 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b 73 71  6 text using [sq
2cbd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2cbe0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2cbf0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2cc00 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2cc10 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2cc20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2cc30 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2cc40 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2cc50 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2cc60 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49  ndex()]..*/.SQLI
2cc70 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2cc80 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2cc90 72 5f 69 6e 64 65 78 28 73 71 6c 69 74 65 33 5f  r_index(sqlite3_
2cca0 73 74 6d 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  stmt*, const cha
2ccb0 72 20 2a 7a 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a  r *zName);../*.*
2ccc0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2ccd0 74 20 41 6c 6c 20 42 69 6e 64 69 6e 67 73 20 4f  t All Bindings O
2cce0 6e 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  n A Prepared Sta
2ccf0 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f  tement.**.** ^Co
2cd00 6e 74 72 61 72 79 20 74 6f 20 74 68 65 20 69 6e  ntrary to the in
2cd10 74 75 69 74 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c  tuition of many,
2cd20 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2cd30 29 5d 20 64 6f 65 73 20 6e 6f 74 20 72 65 73 65  )] does not rese
2cd40 74 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  t.** the [sqlite
2cd50 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 69  3_bind_blob | bi
2cd60 6e 64 69 6e 67 73 5d 20 6f 6e 20 61 20 5b 70 72  ndings] on a [pr
2cd70 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2cd80 5d 2e 0a 2a 2a 20 5e 55 73 65 20 74 68 69 73 20  ]..** ^Use this 
2cd90 72 6f 75 74 69 6e 65 20 74 6f 20 72 65 73 65 74  routine to reset
2cda0 20 61 6c 6c 20 68 6f 73 74 20 70 61 72 61 6d 65   all host parame
2cdb0 74 65 72 73 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f  ters to NULL..*/
2cdc0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2cdd0 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69  sqlite3_clear_bi
2cde0 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2cdf0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2ce00 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
2ce10 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52  f Columns In A R
2ce20 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
2ce30 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62  ^Return the numb
2ce40 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2ce50 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2ce60 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a  returned by the.
2ce70 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
2ce80 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72  tement]. ^This r
2ce90 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30  outine returns 0
2cea0 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20   if pStmt is an 
2ceb0 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  SQL.** statement
2cec0 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72   that does not r
2ced0 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20  eturn data (for 
2cee0 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41  example an [UPDA
2cef0 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  TE])..**.** See 
2cf00 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64  also: [sqlite3_d
2cf10 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a  ata_count()].*/.
2cf20 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
2cf30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f  qlite3_column_co
2cf40 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2cf50 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2cf60 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75 6d   CAPI3REF: Colum
2cf70 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65 73  n Names In A Res
2cf80 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult Set.**.** ^T
2cf90 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2cfa0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61 73  turn the name as
2cfb0 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72 74  signed to a part
2cfc0 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a 2a  icular column.**
2cfd0 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73   in the result s
2cfe0 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d  et of a [SELECT]
2cff0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54 68   statement.  ^Th
2d000 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2d010 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65 72  _name().** inter
2d020 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
2d030 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72 6f  ointer to a zero
2d040 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
2d050 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64 20  8 string.** and 
2d060 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e  sqlite3_column_n
2d070 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73 20  ame16() returns 
2d080 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2d090 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  ero-terminated.*
2d0a0 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  * UTF-16 string.
2d0b0 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72    ^The first par
2d0c0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 70  ameter is the [p
2d0d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d0e0 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c 65  t].** that imple
2d0f0 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45 43  ments the [SELEC
2d100 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e 54  T] statement. ^T
2d110 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2d120 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63 6f  ter is the.** co
2d130 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e 54  lumn number.  ^T
2d140 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75  he leftmost colu
2d150 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e 0a  mn is number 0..
2d160 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
2d170 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ned string point
2d180 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69  er is valid unti
2d190 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70 72  l either the [pr
2d1a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2d1b0 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79 65  ].** is destroye
2d1c0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 69  d by [sqlite3_fi
2d1d0 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e 74  nalize()] or unt
2d1e0 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  il the statement
2d1f0 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
2d200 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64 20  y.** reprepared 
2d210 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  by the first cal
2d220 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
2d230 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72 74  ep()] for a part
2d240 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f 72  icular run.** or
2d250 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 20   until the next 
2d260 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  call to.** sqlit
2d270 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29  e3_column_name()
2d280 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2d290 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20 74  mn_name16() on t
2d2a0 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e 0a  he same column..
2d2b0 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  **.** ^If sqlite
2d2c0 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  3_malloc() fails
2d2d0 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f 63   during the proc
2d2e0 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65 72  essing of either
2d2f0 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f 72   routine.** (for
2d300 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67 20   example during 
2d310 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72 6f  a conversion fro
2d320 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d 31  m UTF-8 to UTF-1
2d330 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55 4c  6) then a.** NUL
2d340 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2d350 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  urned..**.** ^Th
2d360 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73 75  e name of a resu
2d370 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68 65  lt column is the
2d380 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22 41   value of the "A
2d390 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a 2a  S" clause for.**
2d3a0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69 66   that column, if
2d3b0 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53 20   there is an AS 
2d3c0 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65 72  clause.  If ther
2d3d0 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75 73  e is no AS claus
2d3e0 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e 61  e.** then the na
2d3f0 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e  me of the column
2d400 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64 20   is unspecified 
2d410 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20 66  and may change f
2d420 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65 61  rom.** one relea
2d430 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f 20  se of SQLite to 
2d440 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 53 51 4c  the next..*/.SQL
2d450 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2d460 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2d470 6d 6e 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f  mn_name(sqlite3_
2d480 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  stmt*, int N);.S
2d490 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2d4a0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2d4b0 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
2d4c0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2d4d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2d4e0 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
2d4f0 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
2d500 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
2d510 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
2d520 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
2d530 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
2d540 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2d550 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
2d560 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
2d570 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
2d580 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
2d590 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
2d5a0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
2d5b0 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2d5c0 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
2d5d0 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
2d5e0 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
2d5f0 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
2d600 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2d610 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
2d620 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
2d630 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
2d640 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
2d650 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
2d660 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
2d670 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
2d680 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
2d690 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
2d6a0 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
2d6b0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2d6c0 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
2d6d0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2d6e0 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
2d6f0 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
2d700 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d710 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2d720 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2d730 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2d740 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2d750 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2d760 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2d770 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2d780 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2d790 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
2d7a0 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
2d7b0 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
2d7c0 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
2d7d0 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
2d7e0 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
2d7f0 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
2d800 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
2d810 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
2d820 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2d830 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2d840 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2d850 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
2d860 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
2d870 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2d880 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
2d890 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
2d8a0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
2d8b0 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
2d8c0 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2d8d0 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
2d8e0 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
2d8f0 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2d900 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
2d910 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
2d920 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
2d930 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
2d940 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
2d950 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
2d960 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
2d970 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
2d980 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
2d990 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
2d9a0 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
2d9b0 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
2d9c0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2d9d0 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
2d9e0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
2d9f0 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
2da00 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
2da10 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2da20 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
2da30 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
2da40 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2da50 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
2da60 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2da70 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
2da80 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
2da90 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
2daa0 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
2dab0 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
2dac0 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
2dad0 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
2dae0 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
2daf0 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
2db00 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
2db10 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
2db20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2db30 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
2db40 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
2db50 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2db60 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2db70 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2db80 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2db90 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2dba0 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2dbb0 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
2dbc0 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2dbd0 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2dbe0 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
2dbf0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
2dc00 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
2dc10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dc20 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
2dc30 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2dc40 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2dc50 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
2dc60 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2dc70 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2dc80 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
2dc90 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2dca0 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2dcb0 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
2dcc0 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
2dcd0 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
2dce0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2dcf0 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
2dd00 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
2dd10 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2dd20 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2dd30 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 53 51 4c  ndefined..*/.SQL
2dd40 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
2dd50 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2dd60 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2dd70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2dd80 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2dd90 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2dda0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62  te3_column_datab
2ddb0 61 73 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ase_name16(sqlit
2ddc0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53  e3_stmt*,int);.S
2ddd0 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2dde0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2ddf0 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28  lumn_table_name(
2de00 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2de10 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  t);.SQLITE_API c
2de20 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2de30 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
2de40 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2de50 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2de60 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72  E_API const char
2de70 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2de80 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 28 73 71 6c  _origin_name(sql
2de90 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2dea0 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2deb0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2dec0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2ded0 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2dee0 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2def0 43 41 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72  CAPI3REF: Declar
2df00 65 64 20 44 61 74 61 74 79 70 65 20 4f 66 20 41  ed Datatype Of A
2df10 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a   Query Result.**
2df20 0a 2a 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20  .** ^(The first 
2df30 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b  parameter is a [
2df40 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2df50 6e 74 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  nt]..** If this 
2df60 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b  statement is a [
2df70 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e  SELECT] statemen
2df80 74 20 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f  t and the Nth co
2df90 6c 75 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72  lumn of the.** r
2dfa0 65 74 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73  eturned result s
2dfb0 65 74 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45  et of that [SELE
2dfc0 43 54 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63  CT] is a table c
2dfd0 6f 6c 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a  olumn (not an.**
2dfe0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
2dff0 75 62 71 75 65 72 79 29 20 74 68 65 6e 20 74 68  ubquery) then th
2e000 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65 20  e declared type 
2e010 6f 66 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20  of the table.** 
2e020 63 6f 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e  column is return
2e030 65 64 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e  ed.)^  ^If the N
2e040 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65  th column of the
2e050 20 72 65 73 75 6c 74 20 73 65 74 20 69 73 20 61   result set is a
2e060 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20  n.** expression 
2e070 6f 72 20 73 75 62 71 75 65 72 79 2c 20 74 68 65  or subquery, the
2e080 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  n a NULL pointer
2e090 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
2e0a0 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20 73   ^The returned s
2e0b0 74 72 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20  tring is always 
2e0c0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a  UTF-8 encoded..*
2e0d0 2a 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70  *.** ^(For examp
2e0e0 6c 65 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61  le, given the da
2e0f0 74 61 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a  tabase schema:.*
2e100 2a 0a 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c  *.** CREATE TABL
2e110 45 20 74 31 28 63 31 20 56 41 52 49 41 4e 54 29  E t1(c1 VARIANT)
2e120 3b 0a 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20  ;.**.** and the 
2e130 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d  following statem
2e140 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c  ent to be compil
2e150 65 64 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54  ed:.**.** SELECT
2e160 20 63 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d   c1 + 1, c1 FROM
2e170 20 74 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20   t1;.**.** this 
2e180 72 6f 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65  routine would re
2e190 74 75 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20  turn the string 
2e1a0 22 56 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68  "VARIANT" for th
2e1b0 65 20 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a  e second result.
2e1c0 2a 2a 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29  ** column (i==1)
2e1d0 2c 20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69  , and a NULL poi
2e1e0 6e 74 65 72 20 66 6f 72 20 74 68 65 20 66 69 72  nter for the fir
2e1f0 73 74 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  st result column
2e200 20 28 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a   (i==0).)^.**.**
2e210 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 64 79   ^SQLite uses dy
2e220 6e 61 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74  namic run-time t
2e230 79 70 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74  yping.  ^So just
2e240 20 62 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d   because a colum
2e250 6e 0a 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64  n.** is declared
2e260 20 74 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61   to contain a pa
2e270 72 74 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f  rticular type do
2e280 65 73 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74  es not mean that
2e290 20 74 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f   the.** data sto
2e2a0 72 65 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75  red in that colu
2e2b0 6d 6e 20 69 73 20 6f 66 20 74 68 65 20 64 65 63  mn is of the dec
2e2c0 6c 61 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c  lared type.  SQL
2e2d0 69 74 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67  ite is.** strong
2e2e0 6c 79 20 74 79 70 65 64 2c 20 62 75 74 20 74 68  ly typed, but th
2e2f0 65 20 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61  e typing is dyna
2e300 6d 69 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20  mic not static. 
2e310 20 5e 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73   ^Type.** is ass
2e320 6f 63 69 61 74 65 64 20 77 69 74 68 20 69 6e 64  ociated with ind
2e330 69 76 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20  ividual values, 
2e340 6e 6f 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e  not with the con
2e350 74 61 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20  tainers.** used 
2e360 74 6f 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61  to hold those va
2e370 6c 75 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  lues..*/.SQLITE_
2e380 41 50 49 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  API const char *
2e390 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2e3a0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2e3b0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49  stmt*,int);.SQLI
2e3c0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
2e3d0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2e3e0 6e 5f 64 65 63 6c 74 79 70 65 31 36 28 73 71 6c  n_decltype16(sql
2e3f0 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2e400 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2e410 3a 20 45 76 61 6c 75 61 74 65 20 41 6e 20 53 51  : Evaluate An SQ
2e420 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a  L Statement.**.*
2e430 2a 20 41 66 74 65 72 20 61 20 5b 70 72 65 70 61  * After a [prepa
2e440 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 68  red statement] h
2e450 61 73 20 62 65 65 6e 20 70 72 65 70 61 72 65 64  as been prepared
2e460 20 75 73 69 6e 67 20 65 69 74 68 65 72 0a 2a 2a   using either.**
2e470 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e480 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69  e_v2()] or [sqli
2e490 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2e4a0 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  ()] or one of th
2e4b0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2e4c0 72 66 61 63 65 73 20 5b 73 71 6c 69 74 65 33 5f  rfaces [sqlite3_
2e4d0 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 5b 73  prepare()] or [s
2e4e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2e4f0 28 29 5d 2c 20 74 68 69 73 20 66 75 6e 63 74 69  ()], this functi
2e500 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65 20 63 61  on.** must be ca
2e510 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  lled one or more
2e520 20 74 69 6d 65 73 20 74 6f 20 65 76 61 6c 75 61   times to evalua
2e530 74 65 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  te the statement
2e540 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64 65 74 61  ..**.** The deta
2e550 69 6c 73 20 6f 66 20 74 68 65 20 62 65 68 61 76  ils of the behav
2e560 69 6f 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74  ior of the sqlit
2e570 65 33 5f 73 74 65 70 28 29 20 69 6e 74 65 72 66  e3_step() interf
2e580 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a 20 6f 6e  ace depend.** on
2e590 20 77 68 65 74 68 65 72 20 74 68 65 20 73 74 61   whether the sta
2e5a0 74 65 6d 65 6e 74 20 77 61 73 20 70 72 65 70 61  tement was prepa
2e5b0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 6e 65  red using the ne
2e5c0 77 65 72 20 22 76 32 22 20 69 6e 74 65 72 66 61  wer "v2" interfa
2e5d0 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  ce.** [sqlite3_p
2e5e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
2e5f0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2e600 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 74 68 65  e16_v2()] or the
2e610 20 6f 6c 64 65 72 20 6c 65 67 61 63 79 0a 2a 2a   older legacy.**
2e620 20 69 6e 74 65 72 66 61 63 65 20 5b 73 71 6c 69   interface [sqli
2e630 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61  te3_prepare()] a
2e640 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  nd [sqlite3_prep
2e650 61 72 65 31 36 28 29 5d 2e 20 20 54 68 65 20 75  are16()].  The u
2e660 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20 6e 65 77  se of the.** new
2e670 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 20   "v2" interface 
2e680 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  is recommended f
2e690 6f 72 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  or new applicati
2e6a0 6f 6e 73 20 62 75 74 20 74 68 65 20 6c 65 67 61  ons but the lega
2e6b0 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2e6c0 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f  will continue to
2e6d0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 0a 2a   be supported..*
2e6e0 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 6c 65 67  *.** ^In the leg
2e6f0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 74  acy interface, t
2e700 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20  he return value 
2e710 77 69 6c 6c 20 62 65 20 65 69 74 68 65 72 20 5b  will be either [
2e720 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 0a 2a 2a  SQLITE_BUSY],.**
2e730 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 20   [SQLITE_DONE], 
2e740 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 5b 53  [SQLITE_ROW], [S
2e750 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c 20 6f 72  QLITE_ERROR], or
2e760 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2e770 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 22  ..** ^With the "
2e780 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c 20 61  v2" interface, a
2e790 6e 79 20 6f 66 20 74 68 65 20 6f 74 68 65 72 20  ny of the other 
2e7a0 5b 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6f  [result codes] o
2e7b0 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  r.** [extended r
2e7c0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 6d 69 67  esult codes] mig
2e7d0 68 74 20 62 65 20 72 65 74 75 72 6e 65 64 20 61  ht be returned a
2e7e0 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 5b  s well..**.** ^[
2e7f0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6d 65 61  SQLITE_BUSY] mea
2e800 6e 73 20 74 68 61 74 20 74 68 65 20 64 61 74 61  ns that the data
2e810 62 61 73 65 20 65 6e 67 69 6e 65 20 77 61 73 20  base engine was 
2e820 75 6e 61 62 6c 65 20 74 6f 20 61 63 71 75 69 72  unable to acquir
2e830 65 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  e the.** databas
2e840 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65 65 64 73  e locks it needs
2e850 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f 62 2e 20   to do its job. 
2e860 20 5e 49 66 20 74 68 65 20 73 74 61 74 65 6d 65   ^If the stateme
2e870 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d 49 54 5d  nt is a [COMMIT]
2e880 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73 20 6f 75  .** or occurs ou
2e890 74 73 69 64 65 20 6f 66 20 61 6e 20 65 78 70 6c  tside of an expl
2e8a0 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  icit transaction
2e8b0 2c 20 74 68 65 6e 20 79 6f 75 20 63 61 6e 20 72  , then you can r
2e8c0 65 74 72 79 20 74 68 65 0a 2a 2a 20 73 74 61 74  etry the.** stat
2e8d0 65 6d 65 6e 74 2e 20 20 49 66 20 74 68 65 20 73  ement.  If the s
2e8e0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 6f 74 20  tatement is not 
2e8f0 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e 64 20 6f  a [COMMIT] and o
2e900 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 6e 0a  ccurs within an.
2e910 2a 2a 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  ** explicit tran
2e920 73 61 63 74 69 6f 6e 20 74 68 65 6e 20 79 6f 75  saction then you
2e930 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62 61 63 6b   should rollback
2e940 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
2e950 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f 6e 74 69   before.** conti
2e960 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53  nuing..**.** ^[S
2e970 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d 65 61 6e  QLITE_DONE] mean
2e980 73 20 74 68 61 74 20 74 68 65 20 73 74 61 74 65  s that the state
2e990 6d 65 6e 74 20 68 61 73 20 66 69 6e 69 73 68 65  ment has finishe
2e9a0 64 20 65 78 65 63 75 74 69 6e 67 0a 2a 2a 20 73  d executing.** s
2e9b0 75 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 73 71  uccessfully.  sq
2e9c0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 73 68 6f  lite3_step() sho
2e9d0 75 6c 64 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65  uld not be calle
2e9e0 64 20 61 67 61 69 6e 20 6f 6e 20 74 68 69 73 20  d again on this 
2e9f0 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2ea00 6e 65 20 77 69 74 68 6f 75 74 20 66 69 72 73 74  ne without first
2ea10 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2ea20 33 5f 72 65 73 65 74 28 29 5d 20 74 6f 20 72 65  3_reset()] to re
2ea30 73 65 74 20 74 68 65 20 76 69 72 74 75 61 6c 0a  set the virtual.
2ea40 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61 63 6b 20  ** machine back 
2ea50 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73  to its initial s
2ea60 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  tate..**.** ^If 
2ea70 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
2ea80 74 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64  t being executed
2ea90 20 72 65 74 75 72 6e 73 20 61 6e 79 20 64 61 74   returns any dat
2eaa0 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f  a, then [SQLITE_
2eab0 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  ROW].** is retur
2eac0 6e 65 64 20 65 61 63 68 20 74 69 6d 65 20 61 20  ned each time a 
2ead0 6e 65 77 20 72 6f 77 20 6f 66 20 64 61 74 61 20  new row of data 
2eae0 69 73 20 72 65 61 64 79 20 66 6f 72 20 70 72 6f  is ready for pro
2eaf0 63 65 73 73 69 6e 67 20 62 79 20 74 68 65 0a 2a  cessing by the.*
2eb00 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65 20 76 61  * caller. The va
2eb10 6c 75 65 73 20 6d 61 79 20 62 65 20 61 63 63 65  lues may be acce
2eb20 73 73 65 64 20 75 73 69 6e 67 20 74 68 65 20 5b  ssed using the [
2eb30 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75  column access fu
2eb40 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 73 71 6c  nctions]..** sql
2eb50 69 74 65 33 5f 73 74 65 70 28 29 20 69 73 20 63  ite3_step() is c
2eb60 61 6c 6c 65 64 20 61 67 61 69 6e 20 74 6f 20 72  alled again to r
2eb70 65 74 72 69 65 76 65 20 74 68 65 20 6e 65 78 74  etrieve the next
2eb80 20 72 6f 77 20 6f 66 20 64 61 74 61 2e 0a 2a 2a   row of data..**
2eb90 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 45 52 52  .** ^[SQLITE_ERR
2eba0 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 61  OR] means that a
2ebb0 20 72 75 6e 2d 74 69 6d 65 20 65 72 72 6f 72 20   run-time error 
2ebc0 28 73 75 63 68 20 61 73 20 61 20 63 6f 6e 73 74  (such as a const
2ebd0 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c 61 74 69  raint.** violati
2ebe0 6f 6e 29 20 68 61 73 20 6f 63 63 75 72 72 65 64  on) has occurred
2ebf0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2ec00 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2ec10 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 0a  called again on.
2ec20 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f 72 65 20  ** the VM. More 
2ec30 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d 61 79 20  information may 
2ec40 62 65 20 66 6f 75 6e 64 20 62 79 20 63 61 6c 6c  be found by call
2ec50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  ing [sqlite3_err
2ec60 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57 69 74 68  msg()]..** ^With
2ec70 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2ec80 72 66 61 63 65 2c 20 61 20 6d 6f 72 65 20 73 70  rface, a more sp
2ec90 65 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64  ecific error cod
2eca0 65 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 2c 0a  e (for example,.
2ecb0 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  ** [SQLITE_INTER
2ecc0 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 53  RUPT], [SQLITE_S
2ecd0 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49 54 45 5f  CHEMA], [SQLITE_
2ece0 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64 20 73 6f  CORRUPT], and so
2ecf0 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61 6e 20 62   forth).** can b
2ed00 65 20 6f 62 74 61 69 6e 65 64 20 62 79 20 63 61  e obtained by ca
2ed10 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  lling [sqlite3_r
2ed20 65 73 65 74 28 29 5d 20 6f 6e 20 74 68 65 0a 2a  eset()] on the.*
2ed30 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2ed40 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20 74 68 65  ement].  ^In the
2ed50 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2c   "v2" interface,
2ed60 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 70 65  .** the more spe
2ed70 63 69 66 69 63 20 65 72 72 6f 72 20 63 6f 64 65  cific error code
2ed80 20 69 73 20 72 65 74 75 72 6e 65 64 20 64 69 72   is returned dir
2ed90 65 63 74 6c 79 20 62 79 20 73 71 6c 69 74 65 33  ectly by sqlite3
2eda0 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a 2a 20 5b  _step()..**.** [
2edb0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 6d  SQLITE_MISUSE] m
2edc0 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 74 68  eans that the th
2edd0 69 73 20 72 6f 75 74 69 6e 65 20 77 61 73 20 63  is routine was c
2ede0 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f 70 72 69  alled inappropri
2edf0 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72 68 61 70  ately..** Perhap
2ee00 73 20 69 74 20 77 61 73 20 63 61 6c 6c 65 64 20  s it was called 
2ee10 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
2ee20 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
2ee30 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79 20 62 65  as.** already be
2ee40 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  en [sqlite3_fina
2ee50 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 64  lize | finalized
2ee60 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74 68 61 74  ] or on one that
2ee70 20 68 61 64 0a 2a 2a 20 70 72 65 76 69 6f 75 73   had.** previous
2ee80 6c 79 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  ly returned [SQL
2ee90 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72 20 5b 53  ITE_ERROR] or [S
2eea0 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 4f 72  QLITE_DONE].  Or
2eeb0 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20 62 65 20   it could.** be 
2eec0 74 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68  the case that th
2eed0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
2eee0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 62 65  connection is be
2eef0 69 6e 67 20 75 73 65 64 20 62 79 20 74 77 6f 20  ing used by two 
2ef00 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68 72 65 61  or.** more threa
2ef10 64 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 6d  ds at the same m
2ef20 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 2a  oment in time..*
2ef30 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20 76 65 72  *.** For all ver
2ef40 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
2ef50 75 70 20 74 6f 20 61 6e 64 20 69 6e 63 6c 75 64  up to and includ
2ef60 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c 20 61 20  ing 3.6.23.1, a 
2ef70 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2ef80 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 61 73  te3_reset()] was
2ef90 20 72 65 71 75 69 72 65 64 20 61 66 74 65 72 20   required after 
2efa0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 72  sqlite3_step() r
2efb0 65 74 75 72 6e 65 64 20 61 6e 79 74 68 69 6e 67  eturned anything
2efc0 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  .** other than [
2efd0 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62 65 66 6f  SQLITE_ROW] befo
2efe0 72 65 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  re any subsequen
2eff0 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 0a  t invocation of.
2f000 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2f010 29 2e 20 20 46 61 69 6c 75 72 65 20 74 6f 20 72  ).  Failure to r
2f020 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2f030 64 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  d statement usin
2f040 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  g .** [sqlite3_r
2f050 65 73 65 74 28 29 5d 20 77 6f 75 6c 64 20 72 65  eset()] would re
2f060 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53 51 4c 49  sult in an [SQLI
2f070 54 45 5f 4d 49 53 55 53 45 5d 20 72 65 74 75 72  TE_MISUSE] retur
2f080 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65  n from.** sqlite
2f090 33 5f 73 74 65 70 28 29 2e 20 20 42 75 74 20 61  3_step().  But a
2f0a0 66 74 65 72 20 76 65 72 73 69 6f 6e 20 33 2e 36  fter version 3.6
2f0b0 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65 33 5f 73  .23.1, sqlite3_s
2f0c0 74 65 70 28 29 20 62 65 67 61 6e 0a 2a 2a 20 63  tep() began.** c
2f0d0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2f0e0 72 65 73 65 74 28 29 5d 20 61 75 74 6f 6d 61 74  reset()] automat
2f0f0 69 63 61 6c 6c 79 20 69 6e 20 74 68 69 73 20 63  ically in this c
2f100 69 72 63 75 6d 73 74 61 6e 63 65 20 72 61 74 68  ircumstance rath
2f110 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65 74 75 72  er.** than retur
2f120 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 4d 49 53  ning [SQLITE_MIS
2f130 55 53 45 5d 2e 20 20 54 68 69 73 20 69 73 20 6e  USE].  This is n
2f140 6f 74 20 63 6f 6e 73 69 64 65 72 65 64 20 61 20  ot considered a 
2f150 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 0a 2a 2a  compatibility.**
2f160 20 62 72 65 61 6b 20 62 65 63 61 75 73 65 20 61   break because a
2f170 6e 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  ny application t
2f180 68 61 74 20 65 76 65 72 20 72 65 63 65 69 76 65  hat ever receive
2f190 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55  s an SQLITE_MISU
2f1a0 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69 73 20 62  SE error.** is b
2f1b0 72 6f 6b 65 6e 20 62 79 20 64 65 66 69 6e 69 74  roken by definit
2f1c0 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ion.  The [SQLIT
2f1d0 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45 53 45 54  E_OMIT_AUTORESET
2f1e0 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
2f1f0 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20 62 65 20  ption.** can be 
2f200 75 73 65 64 20 74 6f 20 72 65 73 74 6f 72 65 20  used to restore 
2f210 74 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76  the legacy behav
2f220 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 47 6f  ior..**.** <b>Go
2f230 6f 66 79 20 49 6e 74 65 72 66 61 63 65 20 41 6c  ofy Interface Al
2f240 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74 68 65 20  ert:</b> In the 
2f250 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2f260 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 74  , the sqlite3_st
2f270 65 70 28 29 0a 2a 2a 20 41 50 49 20 61 6c 77 61  ep().** API alwa
2f280 79 73 20 72 65 74 75 72 6e 73 20 61 20 67 65 6e  ys returns a gen
2f290 65 72 69 63 20 65 72 72 6f 72 20 63 6f 64 65 2c  eric error code,
2f2a0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2f2b0 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 0a 2a   following any.*
2f2c0 2a 20 65 72 72 6f 72 20 6f 74 68 65 72 20 74 68  * error other th
2f2d0 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  an [SQLITE_BUSY]
2f2e0 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 4d 49 53   and [SQLITE_MIS
2f2f0 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75 73 74 20  USE].  You must 
2f300 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  call.** [sqlite3
2f310 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71  _reset()] or [sq
2f320 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2f330 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69  ] in order to fi
2f340 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a 2a  nd one of the.**
2f350 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2f360 20 63 6f 64 65 73 5d 20 74 68 61 74 20 62 65 74   codes] that bet
2f370 74 65 72 20 64 65 73 63 72 69 62 65 73 20 74 68  ter describes th
2f380 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57 65 20 61  e error..** We a
2f390 64 6d 69 74 20 74 68 61 74 20 74 68 69 73 20 69  dmit that this i
2f3a0 73 20 61 20 67 6f 6f 66 79 20 64 65 73 69 67 6e  s a goofy design
2f3b0 2e 20 20 54 68 65 20 70 72 6f 62 6c 65 6d 20 68  .  The problem h
2f3c0 61 73 20 62 65 65 6e 20 66 69 78 65 64 0a 2a 2a  as been fixed.**
2f3d0 20 77 69 74 68 20 74 68 65 20 22 76 32 22 20 69   with the "v2" i
2f3e0 6e 74 65 72 66 61 63 65 2e 20 20 49 66 20 79 6f  nterface.  If yo
2f3f0 75 20 70 72 65 70 61 72 65 20 61 6c 6c 20 6f 66  u prepare all of
2f400 20 79 6f 75 72 20 53 51 4c 20 73 74 61 74 65 6d   your SQL statem
2f410 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67 20 65 69  ents.** using ei
2f420 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ther [sqlite3_pr
2f430 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
2f440 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2f450 36 5f 76 32 28 29 5d 20 69 6e 73 74 65 61 64 0a  6_v2()] instead.
2f460 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ** of the legacy
2f470 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f480 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2f490 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 69  3_prepare16()] i
2f4a0 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a 20 74 68  nterfaces,.** th
2f4b0 65 6e 20 74 68 65 20 6d 6f 72 65 20 73 70 65 63  en the more spec
2f4c0 69 66 69 63 20 5b 65 72 72 6f 72 20 63 6f 64 65  ific [error code
2f4d0 73 5d 20 61 72 65 20 72 65 74 75 72 6e 65 64 20  s] are returned 
2f4e0 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62 79 20 73  directly.** by s
2f4f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2f500 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 22  The use of the "
2f510 76 32 22 20 69 6e 74 65 72 66 61 63 65 20 69 73  v2" interface is
2f520 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2f   recommended..*/
2f530 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2f540 73 71 6c 69 74 65 33 5f 73 74 65 70 28 73 71 6c  sqlite3_step(sql
2f550 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2f560 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2f570 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
2f580 69 6e 20 61 20 72 65 73 75 6c 74 20 73 65 74 0a  in a result set.
2f590 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2f5a0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29  e3_data_count(P)
2f5b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2f5c0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2f5d0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a   columns in the.
2f5e0 2a 2a 20 63 75 72 72 65 6e 74 20 72 6f 77 20 6f  ** current row o
2f5f0 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2f600 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74   of [prepared st
2f610 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e  atement] P..** ^
2f620 49 66 20 70 72 65 70 61 72 65 64 20 73 74 61 74  If prepared stat
2f630 65 6d 65 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74  ement P does not
2f640 20 68 61 76 65 20 72 65 73 75 6c 74 73 20 72 65   have results re
2f650 61 64 79 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ady to return.**
2f660 20 28 76 69 61 20 63 61 6c 6c 73 20 74 6f 20 74   (via calls to t
2f670 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  he [sqlite3_colu
2f680 6d 6e 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33  mn_int | sqlite3
2f690 5f 63 6f 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a  _column_*()] of.
2f6a0 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 29 20 74  ** interfaces) t
2f6b0 68 65 6e 20 73 71 6c 69 74 65 33 5f 64 61 74 61  hen sqlite3_data
2f6c0 5f 63 6f 75 6e 74 28 50 29 20 72 65 74 75 72 6e  _count(P) return
2f6d0 73 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s 0..** ^The sql
2f6e0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2f6f0 50 29 20 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20  P) routine also 
2f700 72 65 74 75 72 6e 73 20 30 20 69 66 20 50 20 69  returns 0 if P i
2f710 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2f720 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2f730 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2f740 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2f750 30 20 69 66 20 74 68 65 20 70 72 65 76 69 6f 75  0 if the previou
2f760 73 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  s call to.** [sq
2f770 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72  lite3_step](P) r
2f780 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2f790 44 4f 4e 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c  DONE].  ^The sql
2f7a0 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2f7b0 50 29 0a 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72  P).** will retur
2f7c0 6e 20 6e 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72  n non-zero if pr
2f7d0 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b  evious call to [
2f7e0 73 71 6c 69 74 65 33 5f 73 74 65 70 5d 28 50 29  sqlite3_step](P)
2f7f0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51   returned.** [SQ
2f800 4c 49 54 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70  LITE_ROW], excep
2f810 74 20 69 6e 20 74 68 65 20 63 61 73 65 20 6f 66  t in the case of
2f820 20 74 68 65 20 5b 50 52 41 47 4d 41 20 69 6e 63   the [PRAGMA inc
2f830 72 65 6d 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d  remental_vacuum]
2f840 0a 2a 2a 20 77 68 65 72 65 20 69 74 20 61 6c 77  .** where it alw
2f850 61 79 73 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ays returns zero
2f860 20 73 69 6e 63 65 20 65 61 63 68 20 73 74 65 70   since each step
2f870 20 6f 66 20 74 68 61 74 20 6d 75 6c 74 69 2d 73   of that multi-s
2f880 74 65 70 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65  tep.** pragma re
2f890 74 75 72 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20  turns 0 columns 
2f8a0 6f 66 20 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53  of data..**.** S
2f8b0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2f8c0 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29  3_column_count()
2f8d0 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ].*/.SQLITE_API 
2f8e0 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61  int sqlite3_data
2f8f0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2f900 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2f910 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
2f920 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79  ndamental Dataty
2f930 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2f940 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a   SQLITE_TEXT.**.
2f950 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65  ** ^(Every value
2f960 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f   in SQLite has o
2f970 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61  ne of five funda
2f980 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73  mental datatypes
2f990 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2f9a0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e  <li> 64-bit sign
2f9b0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c  ed integer.** <l
2f9c0 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66  i> 64-bit IEEE f
2f9d0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2f9e0 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72  mber.** <li> str
2f9f0 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42  ing.** <li> BLOB
2fa00 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a  .** <li> NULL.**
2fa10 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54   </ul>)^.**.** T
2fa20 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61  hese constants a
2fa30 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63  re codes for eac
2fa40 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73  h of those types
2fa50 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
2fa60 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58  t the SQLITE_TEX
2fa70 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61  T constant was a
2fa80 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69  lso used in SQLi
2fa90 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20  te version 2.** 
2faa0 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79  for a completely
2fab0 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69   different meani
2fac0 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  ng.  Software th
2fad0 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74  at links against
2fae0 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20   both.** SQLite 
2faf0 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51  version 2 and SQ
2fb00 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73  Lite version 3 s
2fb10 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45  hould use SQLITE
2fb20 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53  3_TEXT, not.** S
2fb30 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23  QLITE_TEXT..*/.#
2fb40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
2fb50 54 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65  TEGER  1.#define
2fb60 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20   SQLITE_FLOAT   
2fb70 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
2fb80 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65  E_BLOB     4.#de
2fb90 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c  fine SQLITE_NULL
2fba0 20 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51       5.#ifdef SQ
2fbb0 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65  LITE_TEXT.# unde
2fbc0 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65  f SQLITE_TEXT.#e
2fbd0 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  lse.# define SQL
2fbe0 49 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23  ITE_TEXT     3.#
2fbf0 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51  endif.#define SQ
2fc00 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33  LITE3_TEXT     3
2fc10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2fc20 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20  : Result Values 
2fc30 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20  From A Query.** 
2fc40 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d  KEYWORDS: {colum
2fc50 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
2fc60 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ns}.**.** These 
2fc70 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68  routines form th
2fc80 65 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69  e "result set" i
2fc90 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
2fca0 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
2fcb0 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69  return informati
2fcc0 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c  on about a singl
2fcd0 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  e column of the 
2fce0 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c  current.** resul
2fcf0 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79  t row of a query
2fd00 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73  .  ^In every cas
2fd10 65 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  e the first argu
2fd20 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
2fd30 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65  r.** to the [pre
2fd40 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2fd50 20 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65   that is being e
2fd60 76 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73  valuated (the [s
2fd70 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a  qlite3_stmt*].**
2fd80 20 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e   that was return
2fd90 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
2fda0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2fdb0 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72  r one of its var
2fdc0 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68  iants).** and th
2fdd0 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
2fde0 74 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f  t is the index o
2fdf0 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72  f the column for
2fe00 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69   which informati
2fe10 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
2fe20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c  returned. ^The l
2fe30 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f  eftmost column o
2fe40 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  f the result set
2fe50 20 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30   has the index 0
2fe60 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72  ..** ^The number
2fe70 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2fe80 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65  he result can be
2fe90 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e   determined usin
2fea0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  g.** [sqlite3_co
2feb0 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a  lumn_count()]..*
2fec0 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20  *.** If the SQL 
2fed0 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e  statement does n
2fee0 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69  ot currently poi
2fef0 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f  nt to a valid ro
2ff00 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20  w, or if the.** 
2ff10 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20  column index is 
2ff20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68  out of range, th
2ff30 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65  e result is unde
2ff40 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20  fined..** These 
2ff50 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c  routines may onl
2ff60 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e  y be called when
2ff70 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
2ff80 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2ff90 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73  ite3_step()] has
2ffa0 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54   returned [SQLIT
2ffb0 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68  E_ROW] and neith
2ffc0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  er.** [sqlite3_r
2ffd0 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c  eset()] nor [sql
2ffe0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
2fff0 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65   have been calle
30000 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a  d subsequently..
30010 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65  ** If any of the
30020 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30030 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71  called after [sq
30040 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
30050 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69  r.** [sqlite3_fi
30060 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74  nalize()] or aft
30070 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  er [sqlite3_step
30080 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
30090 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74  .** something ot
300a0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
300b0 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c  _ROW], the resul
300c0 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64  ts are undefined
300d0 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33  ..** If [sqlite3
300e0 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c  _step()] or [sql
300f0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
30100 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
30110 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c  ze()].** are cal
30120 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65  led from a diffe
30130 72 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c  rent thread whil
30140 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72  e any of these r
30150 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70  outines.** are p
30160 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65  ending, then the
30170 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
30180 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
30190 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
301a0 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65  n_type() routine
301b0 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20   returns the.** 
301c0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20  [SQLITE_INTEGER 
301d0 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d  | datatype code]
301e0 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c   for the initial
301f0 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66   data type.** of
30200 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75   the result colu
30210 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  mn.  ^The return
30220 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20  ed value is one 
30230 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  of [SQLITE_INTEG
30240 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ER],.** [SQLITE_
30250 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f  FLOAT], [SQLITE_
30260 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  TEXT], [SQLITE_B
30270 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  LOB], or [SQLITE
30280 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c  _NULL].  The val
30290 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62  ue.** returned b
302a0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
302b0 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20  _type() is only 
302c0 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f  meaningful if no
302d0 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73   type.** convers
302e0 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72  ions have occurr
302f0 65 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20  ed as described 
30300 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20  below.  After a 
30310 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c  type conversion,
30320 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65  .** the value re
30330 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
30340 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
30350 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46  is undefined.  F
30360 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e  uture.** version
30370 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20  s of SQLite may 
30380 63 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76  change the behav
30390 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63  ior of sqlite3_c
303a0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20  olumn_type().** 
303b0 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65  following a type
303c0 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a   conversion..**.
303d0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
303e0 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55  t is a BLOB or U
303f0 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e  TF-8 string then
30400 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c   the sqlite3_col
30410 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72  umn_bytes().** r
30420 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
30430 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
30440 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20  es in that BLOB 
30450 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  or string..** ^I
30460 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
30470 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c  a UTF-16 string,
30480 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
30490 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e  lumn_bytes() con
304a0 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
304b0 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64  ing to UTF-8 and
304c0 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
304d0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
304e0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
304f0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
30500 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
30510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
30520 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c  s() uses.** [sql
30530 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d  ite3_snprintf()]
30540 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74   to convert that
30550 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d   value to a UTF-
30560 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74  8 string and ret
30570 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62  urns.** the numb
30580 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
30590 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e  hat string..** ^
305a0 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
305b0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69   NULL, then sqli
305c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
305d0 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
305e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  .**.** ^If the r
305f0 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20  esult is a BLOB 
30600 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  or UTF-16 string
30610 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65   then the sqlite
30620 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
30630 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
30640 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
30650 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
30660 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
30670 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
30680 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73  ult is a UTF-8 s
30690 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
306a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
306b0 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  16() converts.**
306c0 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
306d0 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72  TF-16 and then r
306e0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
306f0 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e  r of bytes..** ^
30700 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
30710 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65   a numeric value
30720 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
30730 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75  lumn_bytes16() u
30740 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ses.** [sqlite3_
30750 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63  snprintf()] to c
30760 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75  onvert that valu
30770 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74  e to a UTF-16 st
30780 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73  ring and returns
30790 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
307a0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
307b0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
307c0 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c  he result is NUL
307d0 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  L, then sqlite3_
307e0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
307f0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
30800 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73  *.** ^The values
30810 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
30820 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
30830 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73  es()] and .** [s
30840 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
30850 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20  tes16()] do not 
30860 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f  include the zero
30870 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20   terminators at 
30880 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68  the end.** of th
30890 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20  e string.  ^For 
308a0 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c  clarity: the val
308b0 75 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a  ues returned by.
308c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
308d0 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
308e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
308f0 62 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74  bytes16()] are t
30900 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
30910 62 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72  bytes in the str
30920 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d  ing, not the num
30930 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72  ber of character
30940 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67  s..**.** ^String
30950 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71  s returned by sq
30960 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
30970 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
30980 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c  column_text16(),
30990 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73  .** even empty s
309a0 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61  trings, are alwa
309b0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
309c0 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e  ed.  ^The return
309d0 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  .** value from s
309e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
309f0 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d  ob() for a zero-
30a00 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61  length BLOB is a
30a10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
30a20 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74  *.** ^The object
30a30 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71   returned by [sq
30a40 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c  lite3_column_val
30a50 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b  ue()] is an.** [
30a60 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
30a70 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30a80 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74  t.  An unprotect
30a90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
30aa0 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f   object.** may o
30ab0 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68  nly be used with
30ac0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76   [sqlite3_bind_v
30ad0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
30ae0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
30af0 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20  e()]..** If the 
30b00 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
30b10 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
30b20 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  ct returned by.*
30b30 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
30b40 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73  n_value()] is us
30b50 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20  ed in any other 
30b60 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63  way, including c
30b70 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69  alls.** to routi
30b80 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65  nes like [sqlite
30b90 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20  3_value_int()], 
30ba0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
30bb0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
30bc0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
30bd0 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  es()], then the 
30be0 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
30bf0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  fined..**.** The
30c00 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65  se routines atte
30c10 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  mpt to convert t
30c20 68 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61  he value where a
30c30 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f  ppropriate.  ^Fo
30c40 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66  r.** example, if
30c50 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
30c60 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20  presentation is 
30c70 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74  FLOAT and a text
30c80 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65   result.** is re
30c90 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65  quested, [sqlite
30ca0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73  3_snprintf()] is
30cb0 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79   used internally
30cc0 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a   to perform the.
30cd0 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75  ** conversion au
30ce0 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28  tomatically.  ^(
30cf0 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61  The following ta
30d00 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20  ble details the 
30d10 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74  conversions.** t
30d20 68 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a  hat are applied:
30d30 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
30d40 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f  te>.** <table bo
30d50 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72  rder="1">.** <tr
30d60 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62  ><th> Internal<b
30d70 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75  r>Type <th> Requ
30d80 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74  ested<br>Type <t
30d90 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a  h>  Conversion.*
30da0 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  *.** <tr><td>  N
30db0 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45  ULL    <td> INTE
30dc0 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  GER   <td> Resul
30dd0 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74  t is 0.** <tr><t
30de0 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e  d>  NULL    <td>
30df0 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
30e00 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a  Result is 0.0.**
30e10 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
30e20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20     <td>   TEXT  
30e30 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
30e40 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
30e50 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
30e60 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
30e70 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
30e80 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a   NULL pointer.**
30e90 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
30ea0 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  R  <td>  FLOAT  
30eb0 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66    <td> Convert f
30ec0 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66  rom integer to f
30ed0 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  loat.** <tr><td>
30ee0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
30ef0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53   TEXT    <td> AS
30f00 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66  CII rendering of
30f10 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20   the integer.** 
30f20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
30f30 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
30f40 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e   <td> Same as IN
30f50 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c  TEGER->TEXT.** <
30f60 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20  tr><td>  FLOAT  
30f70 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
30f80 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
30f90 6d 20 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67  m float to integ
30fa0 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  er.** <tr><td>  
30fb0 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54  FLOAT   <td>   T
30fc0 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
30fd0 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
30fe0 68 65 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e  he float.** <tr>
30ff0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
31000 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
31010 3e 20 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d  > Same as FLOAT-
31020 3e 54 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64  >TEXT.** <tr><td
31030 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
31040 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55  INTEGER   <td> U
31050 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
31060 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c  ><td>  TEXT    <
31070 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
31080 64 3e 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a  d> Use atof().**
31090 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
310a0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
310b0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
310c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
310d0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
310e0 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  ER   <td> Conver
310f0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
31100 73 65 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72  se atoi().** <tr
31110 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
31120 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74  td>  FLOAT    <t
31130 64 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45  d> Convert to TE
31140 58 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66  XT then use atof
31150 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ().** <tr><td>  
31160 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54  BLOB    <td>   T
31170 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20  EXT    <td> Add 
31180 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  a zero terminato
31190 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c  r if needed.** <
311a0 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f  /table>.** </blo
311b0 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a  ckquote>)^.**.**
311c0 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65   The table above
311d0 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65   makes reference
311e0 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c   to standard C l
311f0 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73  ibrary functions
31200 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61   atoi().** and a
31210 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64  tof().  SQLite d
31220 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75  oes not really u
31230 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  se these functio
31240 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a  ns.  It has its.
31250 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e  ** own equivalen
31260 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69  t internal routi
31270 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29  nes.  The atoi()
31280 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65   and atof() name
31290 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e  s are.** used in
312a0 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62   the table for b
312b0 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61 75  revity and becau
312c0 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d 69  se they are fami
312d0 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20  liar to most.** 
312e0 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a  C programmers..*
312f0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77  *.** Note that w
31300 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73  hen type convers
31310 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e  ions occur, poin
31320 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62 79  ters returned by
31330 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20   prior.** calls 
31340 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
31350 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  n_blob(), sqlite
31360 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c  3_column_text(),
31370 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74   and/or.** sqlit
31380 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
31390 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69  () may be invali
313a0 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63  dated..** Type c
313b0 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70  onversions and p
313c0 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74  ointer invalidat
313d0 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72  ions might occur
313e0 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f  .** in the follo
313f0 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a  wing cases:.**.*
31400 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
31410 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
31420 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64  nt is a BLOB and
31430 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31440 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20  text() or.**    
31450 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e    sqlite3_column
31460 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61 6c  _text16() is cal
31470 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72  led.  A zero-ter
31480 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a  minator might.**
31490 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65        need to be
314a0 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73 74   added to the st
314b0 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c  ring.</li>.** <l
314c0 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63  i> The initial c
314d0 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20  ontent is UTF-8 
314e0 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33  text and sqlite3
314f0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
31500 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c  ) or.**      sql
31510 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31520 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  16() is called. 
31530 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
31540 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
31550 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36  *      to UTF-16
31560 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
31570 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
31580 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65 78  nt is UTF-16 tex
31590 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  t and sqlite3_co
315a0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
315b0 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
315c0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73  column_text() is
315d0 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f   called.  The co
315e0 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f  ntent must be co
315f0 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20  nverted.**      
31600 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a  to UTF-8.</li>.*
31610 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43  * </ul>.**.** ^C
31620 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65  onversions betwe
31630 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20  en UTF-16be and 
31640 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77  UTF-16le are alw
31650 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63  ays done in plac
31660 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20  e and do.** not 
31670 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72 69  invalidate a pri
31680 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75  or pointer, thou
31690 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65  gh of course the
316a0 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20   content of the 
316b0 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74  buffer.** that t
316c0 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72  he prior pointer
316d0 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c   references will
316e0 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66   have been modif
316f0 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64  ied.  Other kind
31700 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69  s.** of conversi
31710 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70  on are done in p
31720 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73 20  lace when it is 
31730 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f  possible, but so
31740 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20  metimes they.** 
31750 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65  are not possible
31760 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61   and in those ca
31770 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  ses prior pointe
31780 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74  rs are invalidat
31790 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61  ed..**.** The sa
317a0 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73 74  fest and easiest
317b0 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c   to remember pol
317c0 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65  icy is to invoke
317d0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
317e0 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65  ** in one of the
317f0 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a   following ways:
31800 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20  .**.** <ul>.**  
31810 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75  <li>sqlite3_colu
31820 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77  mn_text() follow
31830 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
31840 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69  lumn_bytes()</li
31850 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
31860 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20  3_column_blob() 
31870 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
31880 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31890 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
318a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
318b0 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64  ext16() followed
318c0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
318d0 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69  mn_bytes16()</li
318e0 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  >.** </ul>.**.**
318f0 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
31900 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c   you should call
31910 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31920 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74  text(),.** sqlit
31930 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
31940 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  , or sqlite3_col
31950 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72  umn_text16() fir
31960 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20  st to force the 
31970 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74  result.** into t
31980 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61  he desired forma
31990 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73  t, then invoke s
319a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
319b0 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  tes() or.** sqli
319c0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
319d0 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65  16() to find the
319e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73   size of the res
319f0 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78  ult.  Do not mix
31a00 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c   calls.** to sql
31a10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
31a20 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
31a30 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68  lumn_blob() with
31a40 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c   calls to.** sql
31a50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
31a60 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f  s16(), and do no
31a70 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73  t mix calls to s
31a80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
31a90 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63  xt16().** with c
31aa0 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f  alls to sqlite3_
31ab0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a  column_bytes()..
31ac0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74  **.** ^The point
31ad0 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  ers returned are
31ae0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74   valid until a t
31af0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f  ype conversion o
31b00 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63  ccurs as.** desc
31b10 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20  ribed above, or 
31b20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73  until [sqlite3_s
31b30 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
31b40 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
31b50 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
31b60 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ize()] is called
31b70 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73  .  ^The memory s
31b80 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c  pace used to hol
31b90 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64  d strings.** and
31ba0 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20   BLOBs is freed 
31bb0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
31bc0 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61  Do <b>not</b> pa
31bd0 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20  ss the pointers 
31be0 72 65 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c  returned.** [sql
31bf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
31c00 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f  ()], [sqlite3_co
31c10 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74  lumn_text()], et
31c20 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69  c. into.** [sqli
31c30 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a  te3_free()]..**.
31c40 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79  ** ^(If a memory
31c50 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f   allocation erro
31c60 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20  r occurs during 
31c70 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f  the evaluation o
31c80 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73  f any.** of thes
31c90 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65  e routines, a de
31ca0 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72  fault value is r
31cb0 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65  eturned.  The de
31cc0 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69  fault value.** i
31cd0 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e 74  s either the int
31ce0 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61  eger 0, the floa
31cf0 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
31d00 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c  r 0.0, or a NULL
31d10 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75  .** pointer.  Su
31d20 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74  bsequent calls t
31d30 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  o [sqlite3_errco
31d40 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  de()] will retur
31d50 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  n.** [SQLITE_NOM
31d60 45 4d 5d 2e 29 5e 0a 2a 2f 0a 53 51 4c 49 54 45  EM].)^.*/.SQLITE
31d70 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
31d80 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
31d90 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
31da0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
31db0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31dc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
31dd0 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
31de0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
31df0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
31e00 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31e10 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
31e20 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c  , int iCol);.SQL
31e30 49 54 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73  ITE_API double s
31e40 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f  qlite3_column_do
31e50 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
31e60 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53  t*, int iCol);.S
31e70 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
31e80 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
31e90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
31ea0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
31eb0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
31ec0 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  t64 sqlite3_colu
31ed0 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  mn_int64(sqlite3
31ee0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
31ef0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
31f00 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
31f10 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
31f20 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  n_text(sqlite3_s
31f30 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
31f40 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
31f50 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
31f60 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
31f70 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
31f80 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41   iCol);.SQLITE_A
31f90 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  PI int sqlite3_c
31fa0 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
31fb0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
31fc0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
31fd0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
31fe0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
31ff0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
32000 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
32010 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
32020 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
32030 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
32040 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
32050 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
32060 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
32070 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
32080 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32090 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
320a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
320b0 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
320c0 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
320d0 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
320e0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
320f0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
32100 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
32110 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
32120 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
32130 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
32140 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
32150 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
32160 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
32170 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
32180 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
32190 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
321a0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
321b0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
321c0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
321d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
321e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
321f0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
32200 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
32210 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
32220 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
32230 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
32240 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
32250 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
32260 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
32270 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
32280 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
32290 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
322a0 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
322b0 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
322c0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
322d0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
322e0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
322f0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
32300 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
32310 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
32320 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
32330 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
32340 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
32350 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
32360 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
32370 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
32380 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
32390 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
323a0 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
323b0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
323c0 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
323d0 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
323e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
323f0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
32400 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32410 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
32420 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
32430 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
32440 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
32450 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
32460 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
32470 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
32480 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
32490 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
324a0 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
324b0 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
324c0 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c  rruption..*/.SQL
324d0 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
324e0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c  te3_finalize(sql
324f0 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
32500 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
32510 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65 70  EF: Reset A Prep
32520 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
32530 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
32540 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 20  sqlite3_reset() 
32550 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c  function is call
32560 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b 70  ed to reset a [p
32570 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
32580 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63  t].** object bac
32590 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61 6c  k to its initial
325a0 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74 6f   state, ready to
325b0 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64 2e   be re-executed.
325c0 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74 61  .** ^Any SQL sta
325d0 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65 73  tement variables
325e0 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65 73   that had values
325f0 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20 75   bound to them u
32600 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c  sing.** the [sql
32610 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c  ite3_bind_blob |
32620 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
32630 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74 68  ) API] retain th
32640 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55  eir values..** U
32650 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61  se [sqlite3_clea
32660 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f  r_bindings()] to
32670 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64 69   reset the bindi
32680 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ngs..**.** ^The 
32690 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
326a0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 73  )] interface res
326b0 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72 65  ets the [prepare
326c0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a  d statement] S.*
326d0 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62 65  * back to the be
326e0 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20 70  ginning of its p
326f0 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  rogram..**.** ^I
32700 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
32710 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74  t call to [sqlit
32720 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20  e3_step(S)] for 
32730 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
32740 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72 65   statement] S re
32750 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
32760 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  OW] or [SQLITE_D
32770 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b  ONE],.** or if [
32780 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
32790 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f 72   has never befor
327a0 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e  e been called on
327b0 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c   S,.** then [sql
327c0 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
327d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
327e0 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  K]..**.** ^If th
327f0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
32800 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
32810 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a  tep(S)] for the.
32820 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
32830 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63 61  tement] S indica
32840 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74 68  ted an error, th
32850 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72  en.** [sqlite3_r
32860 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
32870 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 20   an appropriate 
32880 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a  [error code]..**
32890 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
328a0 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65  3_reset(S)] inte
328b0 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20 63  rface does not c
328c0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 73  hange the values
328d0 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69  .** of any [sqli
328e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69  te3_bind_blob|bi
328f0 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b  ndings] on the [
32900 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
32910 6e 74 5d 20 53 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nt] S..*/.SQLITE
32920 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
32930 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73  _reset(sqlite3_s
32940 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
32950 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72  .** CAPI3REF: Cr
32960 65 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65  eate Or Redefine
32970 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   SQL Functions.*
32980 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e  * KEYWORDS: {fun
32990 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72  ction creation r
329a0 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57  outines}.** KEYW
329b0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
329c0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
329d0 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57  unction}.** KEYW
329e0 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69  ORDS: {applicati
329f0 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66  on-defined SQL f
32a00 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
32a10 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
32a20 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b   (collectively k
32a30 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f  nown as "functio
32a40 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69  n creation routi
32a50 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65  nes").** are use
32a60 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e  d to add SQL fun
32a70 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67  ctions or aggreg
32a80 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66  ates or to redef
32a90 69 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  ine the behavior
32aa0 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20  .** of existing 
32ab0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
32ac0 20 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68   aggregates.  Th
32ad0 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63  e only differenc
32ae0 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68  es between.** th
32af0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
32b00 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69   the text encodi
32b10 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a  ng expected for.
32b20 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  ** the second pa
32b30 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d  rameter (the nam
32b40 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f  e of the functio
32b50 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29  n being created)
32b60 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73  .** and the pres
32b70 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20  ence or absence 
32b80 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  of a destructor 
32b90 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20  callback for.** 
32ba0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
32bb0 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  data pointer..**
32bc0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70  .** ^The first p
32bd0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
32be0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
32bf0 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74  tion] to which t
32c00 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69  he SQL.** functi
32c10 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65  on is to be adde
32c20 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69  d.  ^If an appli
32c30 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65  cation uses more
32c40 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61   than one databa
32c50 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  se.** connection
32c60 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f   then applicatio
32c70 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
32c80 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20  nctions must be 
32c90 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68  added.** to each
32ca0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
32cb0 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e  tion separately.
32cc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
32cd0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
32ce0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
32cf0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  SQL function to 
32d00 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a  be created or.**
32d10 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   redefined.  ^Th
32d20 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  e length of the 
32d30 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20  name is limited 
32d40 74 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20  to 255 bytes in 
32d50 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65  a UTF-8.** repre
32d60 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75  sentation, exclu
32d70 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f  sive of the zero
32d80 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e  -terminator.  ^N
32d90 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d  ote that the nam
32da0 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69  e.** length limi
32db0 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79  t is in UTF-8 by
32dc0 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74  tes, not charact
32dd0 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62  ers nor UTF-16 b
32de0 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20  ytes.  .** ^Any 
32df0 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74  attempt to creat
32e00 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  e a function wit
32e10 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a  h a longer name.
32e20 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69  ** will result i
32e30 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  n [SQLITE_MISUSE
32e40 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64  ] being returned
32e50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
32e60 72 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41  rd parameter (nA
32e70 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75  rg).** is the nu
32e80 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
32e90 73 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66  s that the SQL f
32ea0 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
32eb0 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e  gregate takes. ^
32ec0 49 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  If this paramete
32ed0 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68  r is -1, then th
32ee0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
32ef0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d  r.** aggregate m
32f00 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62  ay take any numb
32f10 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
32f20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68  between 0 and th
32f30 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62  e limit.** set b
32f40 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  y [sqlite3_limit
32f50 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ]([SQLITE_LIMIT_
32f60 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20  FUNCTION_ARG]). 
32f70 20 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a   If the third.**
32f80 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65   parameter is le
32f90 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72  ss than -1 or gr
32fa0 65 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74  eater than 127 t
32fb0 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
32fc0 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64   is.** undefined
32fd0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
32fe0 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65  rth parameter, e
32ff0 54 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69  TextRep, specifi
33000 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49  es what.** [SQLI
33010 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65  TE_UTF8 | text e
33020 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51  ncoding] this SQ
33030 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65  L function prefe
33040 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61  rs for.** its pa
33050 72 61 6d 65 74 65 72 73 2e 20 20 45 76 65 72 79  rameters.  Every
33060 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
33070 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
33080 74 20 62 65 20 61 62 6c 65 20 74 6f 20 77 6f 72  t be able to wor
33090 6b 0a 2a 2a 20 77 69 74 68 20 55 54 46 2d 38 2c  k.** with UTF-8,
330a0 20 55 54 46 2d 31 36 6c 65 2c 20 6f 72 20 55 54   UTF-16le, or UT
330b0 46 2d 31 36 62 65 2e 20 20 42 75 74 20 73 6f 6d  F-16be.  But som
330c0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
330d0 73 20 6d 61 79 20 62 65 0a 2a 2a 20 6d 6f 72 65  s may be.** more
330e0 20 65 66 66 69 63 69 65 6e 74 20 77 69 74 68 20   efficient with 
330f0 6f 6e 65 20 65 6e 63 6f 64 69 6e 67 20 74 68 61  one encoding tha
33100 6e 20 61 6e 6f 74 68 65 72 2e 20 20 5e 41 6e 20  n another.  ^An 
33110 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79 0a  application may.
33120 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65  ** invoke sqlite
33130 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
33140 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  n() or sqlite3_c
33150 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
33160 28 29 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 74  () multiple.** t
33170 69 6d 65 73 20 77 69 74 68 20 74 68 65 20 73 61  imes with the sa
33180 6d 65 20 66 75 6e 63 74 69 6f 6e 20 62 75 74 20  me function but 
33190 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 76  with different v
331a0 61 6c 75 65 73 20 6f 66 20 65 54 65 78 74 52 65  alues of eTextRe
331b0 70 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74  p..** ^When mult
331c0 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  iple implementat
331d0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
331e0 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76   function are av
331f0 61 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a  ailable, SQLite.
33200 2a 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65  ** will pick the
33210 20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76   one that involv
33220 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f  es the least amo
33230 75 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76  unt of data conv
33240 65 72 73 69 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  ersion..** If th
33250 65 72 65 20 69 73 20 6f 6e 6c 79 20 61 20 73 69  ere is only a si
33260 6e 67 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  ngle implementat
33270 69 6f 6e 20 77 68 69 63 68 20 64 6f 65 73 20 6e  ion which does n
33280 6f 74 20 63 61 72 65 20 77 68 61 74 20 74 65 78  ot care what tex
33290 74 0a 2a 2a 20 65 6e 63 6f 64 69 6e 67 20 69 73  t.** encoding is
332a0 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20   used, then the 
332b0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
332c0 73 68 6f 75 6c 64 20 62 65 20 5b 53 51 4c 49 54  should be [SQLIT
332d0 45 5f 41 4e 59 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28  E_ANY]..**.** ^(
332e0 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
332f0 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
33300 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
33310 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
33320 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
33330 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
33340 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
33350 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
33360 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
33370 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
33380 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
33390 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
333a0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
333b0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
333c0 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
333d0 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
333e0 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
333f0 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
33400 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
33410 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
33420 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
33430 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
33440 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
33450 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
33460 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
33470 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
33480 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
33490 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
334a0 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
334b0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
334c0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
334d0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
334e0 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
334f0 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
33500 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
33510 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
33520 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
33530 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
33540 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
33550 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
33560 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
33570 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
33580 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
33590 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
335a0 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
335b0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
335c0 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
335d0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
335e0 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
335f0 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
33600 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
33610 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
33620 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
33630 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
33640 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
33650 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
33660 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
33670 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
33680 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
33690 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
336a0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
336b0 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
336c0 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
336d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
336e0 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
336f0 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
33700 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
33710 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
33720 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
33730 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
33740 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
33750 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
33760 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
33770 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
33780 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
33790 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
337a0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
337b0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
337c0 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
337d0 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
337e0 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
337f0 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
33800 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
33810 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
33820 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
33830 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
33840 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
33850 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
33860 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
33870 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
33880 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
33890 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
338a0 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
338b0 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
338c0 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
338d0 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
338e0 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
338f0 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
33900 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
33910 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
33920 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
33930 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
33940 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
33950 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
33960 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
33970 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
33980 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
33990 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
339a0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
339b0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
339c0 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
339d0 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
339e0 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
339f0 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
33a00 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
33a10 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
33a20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
33a30 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
33a40 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
33a50 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
33a60 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
33a70 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
33a80 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
33a90 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
33aa0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
33ab0 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
33ac0 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
33ad0 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
33ae0 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
33af0 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
33b00 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
33b10 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
33b20 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
33b30 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
33b40 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
33b50 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
33b60 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
33b70 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
33b80 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
33b90 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
33ba0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
33bb0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
33bc0 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
33bd0 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
33be0 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
33bf0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
33c00 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
33c10 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
33c20 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33c30 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
33c40 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  db,.  const char
33c50 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c   *zFunctionName,
33c60 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69  .  int nArg,.  i
33c70 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76  nt eTextRep,.  v
33c80 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69  oid *pApp,.  voi
33c90 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74  d (*xFunc)(sqlit
33ca0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33cb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33cc0 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70  ,.  void (*xStep
33cd0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
33ce0 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76  t*,int,sqlite3_v
33cf0 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20  alue**),.  void 
33d00 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65  (*xFinal)(sqlite
33d10 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 53  3_context*).);.S
33d20 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
33d30 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
33d40 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
33d50 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
33d60 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
33d70 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
33d80 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
33d90 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
33da0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
33db0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33dc0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
33dd0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
33de0 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
33df0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
33e00 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
33e10 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
33e20 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
33e30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
33e40 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
33e50 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20  _function_v2(.  
33e60 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63  sqlite3 *db,.  c
33e70 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63  onst char *zFunc
33e80 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  tionName,.  int 
33e90 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78  nArg,.  int eTex
33ea0 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41  tRep,.  void *pA
33eb0 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75  pp,.  void (*xFu
33ec0 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  nc)(sqlite3_cont
33ed0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
33ee0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
33ef0 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74  d (*xStep)(sqlit
33f00 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c  e3_context*,int,
33f10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29  sqlite3_value**)
33f20 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61  ,.  void (*xFina
33f30 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  l)(sqlite3_conte
33f40 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  xt*),.  void(*xD
33f50 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
33f60 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
33f70 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67  F: Text Encoding
33f80 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  s.**.** These co
33f90 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e  nstant define in
33fa0 74 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74  teger codes that
33fb0 20 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76   represent the v
33fc0 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65  arious.** text e
33fd0 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74  ncodings support
33fe0 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f  ed by SQLite..*/
33ff0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34000 55 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31  UTF8           1
34010 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34020 55 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32  UTF16LE        2
34030 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34040 55 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33  UTF16BE        3
34050 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
34060 55 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34  UTF16          4
34070 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76      /* Use nativ
34080 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a  e byte order */.
34090 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
340a0 4e 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20  NY            5 
340b0 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72     /* sqlite3_cr
340c0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 20 6f 6e  eate_function on
340d0 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ly */.#define SQ
340e0 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
340f0 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
34100 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
34110 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
34120 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
34130 70 72 65 63 61 74 65 64 20 46 75 6e 63 74 69 6f  precated Functio
34140 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41 54 45 44  ns.** DEPRECATED
34150 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
34160 63 74 69 6f 6e 73 20 61 72 65 20 5b 64 65 70 72  ctions are [depr
34170 65 63 61 74 65 64 5d 2e 20 20 49 6e 20 6f 72 64  ecated].  In ord
34180 65 72 20 74 6f 20 6d 61 69 6e 74 61 69 6e 0a 2a  er to maintain.*
34190 2a 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  * backwards comp
341a0 61 74 69 62 69 6c 69 74 79 20 77 69 74 68 20 6f  atibility with o
341b0 6c 64 65 72 20 63 6f 64 65 2c 20 74 68 65 73 65  lder code, these
341c0 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f 6e 74 69   functions conti
341d0 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65 20 73 75  nue .** to be su
341e0 70 70 6f 72 74 65 64 2e 20 20 48 6f 77 65 76 65  pported.  Howeve
341f0 72 2c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  r, new applicati
34200 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76 6f 69 64  ons should avoid
34210 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f 66 20 74  .** the use of t
34220 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
34230 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f 75 72 61   To help encoura
34240 67 65 20 70 65 6f 70 6c 65 20 74 6f 20 61 76 6f  ge people to avo
34250 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74 68 65 73  id.** using thes
34260 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20 77 65 20  e functions, we 
34270 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67 20 74 6f  are not going to
34280 20 74 65 6c 6c 20 79 6f 75 20 77 68 61 74 20 74   tell you what t
34290 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69 66 6e 64  hey do..*/.#ifnd
342a0 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 44  ef SQLITE_OMIT_D
342b0 45 50 52 45 43 41 54 45 44 0a 53 51 4c 49 54 45  EPRECATED.SQLITE
342c0 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45 50 52  _API SQLITE_DEPR
342d0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
342e0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75  e3_aggregate_cou
342f0 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  nt(sqlite3_conte
34300 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
34310 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
34320 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
34330 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
34340 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
34350 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
34360 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
34370 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69 6e 67  transfer_binding
34380 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  s(sqlite3_stmt*,
34390 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b   sqlite3_stmt*);
343a0 0a 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49  .SQLITE_API SQLI
343b0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
343c0 74 20 73 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c  t sqlite3_global
343d0 5f 72 65 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a  _recover(void);.
343e0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
343f0 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69  E_DEPRECATED voi
34400 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64  d sqlite3_thread
34410 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a  _cleanup(void);.
34420 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
34430 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
34440 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
34450 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76 6f  alarm(void(*)(vo
34460 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
34470 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c 73 71 6c  4,int),void*,sql
34480 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e  ite3_int64);.#en
34490 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  dif../*.** CAPI3
344a0 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53  REF: Obtaining S
344b0 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50 61 72 61  QL Function Para
344c0 6d 65 74 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a  meter Values.**.
344d0 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67 75 61 67  ** The C-languag
344e0 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
344f0 20 6f 66 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   of SQL function
34500 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
34510 20 75 73 65 73 0a 2a 2a 20 74 68 69 73 20 73 65   uses.** this se
34520 74 20 6f 66 20 69 6e 74 65 72 66 61 63 65 20 72  t of interface r
34530 6f 75 74 69 6e 65 73 20 74 6f 20 61 63 63 65 73  outines to acces
34540 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  s the parameter 
34550 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65  values on.** the
34560 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
34570 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  regate..**.** Th
34580 65 20 78 46 75 6e 63 20 28 66 6f 72 20 73 63 61  e xFunc (for sca
34590 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f  lar functions) o
345a0 72 20 78 53 74 65 70 20 28 66 6f 72 20 61 67 67  r xStep (for agg
345b0 72 65 67 61 74 65 73 29 20 70 61 72 61 6d 65 74  regates) paramet
345c0 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ers.** to [sqlit
345d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
345e0 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
345f0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
34600 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e  on16()].** defin
34610 65 20 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74  e callbacks that
34620 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
34630 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64  QL functions and
34640 20 61 67 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20   aggregates..** 
34650 54 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  The 3rd paramete
34660 72 20 74 6f 20 74 68 65 73 65 20 63 61 6c 6c 62  r to these callb
34670 61 63 6b 73 20 69 73 20 61 6e 20 61 72 72 61 79  acks is an array
34680 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a   of pointers to.
34690 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ** [protected sq
346a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
346b0 65 63 74 73 2e 20 20 54 68 65 72 65 20 69 73 20  ects.  There is 
346c0 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  one [sqlite3_val
346d0 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a  ue] object for.*
346e0 2a 20 65 61 63 68 20 70 61 72 61 6d 65 74 65 72  * each parameter
346f0 20 74 6f 20 74 68 65 20 53 51 4c 20 66 75 6e 63   to the SQL func
34700 74 69 6f 6e 2e 20 20 54 68 65 73 65 20 72 6f 75  tion.  These rou
34710 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 74  tines are used t
34720 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20 76 61 6c  o.** extract val
34730 75 65 73 20 66 72 6f 6d 20 74 68 65 20 5b 73 71  ues from the [sq
34740 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
34750 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ects..**.** Thes
34760 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
34770 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72 6f 74 65  only with [prote
34780 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
34790 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  ue] objects..** 
347a0 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 75  Any attempt to u
347b0 73 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  se these routine
347c0 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65  s on an [unprote
347d0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
347e0 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65  ue].** object re
347f0 73 75 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e  sults in undefin
34800 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  ed behavior..**.
34810 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
34820 65 73 20 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b  es work just lik
34830 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
34840 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  ing [column acce
34850 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a  ss functions].**
34860 20 65 78 63 65 70 74 20 74 68 61 74 20 20 74 68   except that  th
34870 65 73 65 20 72 6f 75 74 69 6e 65 73 20 74 61 6b  ese routines tak
34880 65 20 61 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74  e a single [prot
34890 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
348a0 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70  lue] object.** p
348b0 6f 69 6e 74 65 72 20 69 6e 73 74 65 61 64 20 6f  ointer instead o
348c0 66 20 61 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  f a [sqlite3_stm
348d0 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61 6e 64 20  t*] pointer and 
348e0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d  an integer colum
348f0 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20  n number..**.** 
34900 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
34910 75 65 5f 74 65 78 74 31 36 28 29 20 69 6e 74 65  ue_text16() inte
34920 72 66 61 63 65 20 65 78 74 72 61 63 74 73 20 61  rface extracts a
34930 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a   UTF-16 string.*
34940 2a 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20  * in the native 
34950 62 79 74 65 2d 6f 72 64 65 72 20 6f 66 20 74 68  byte-order of th
34960 65 20 68 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20  e host machine. 
34970 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
34980 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
34990 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 61  ) and sqlite3_va
349a0 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 20 69  lue_text16le() i
349b0 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 65 78 74  nterfaces.** ext
349c0 72 61 63 74 20 55 54 46 2d 31 36 20 73 74 72 69  ract UTF-16 stri
349d0 6e 67 73 20 61 73 20 62 69 67 2d 65 6e 64 69 61  ngs as big-endia
349e0 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64  n and little-end
349f0 69 61 6e 20 72 65 73 70 65 63 74 69 76 65 6c 79  ian respectively
34a00 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71  ..**.** ^(The sq
34a10 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65  lite3_value_nume
34a20 72 69 63 5f 74 79 70 65 28 29 20 69 6e 74 65 72  ric_type() inter
34a30 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
34a40 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69   apply.** numeri
34a50 63 20 61 66 66 69 6e 69 74 79 20 74 6f 20 74 68  c affinity to th
34a60 65 20 76 61 6c 75 65 2e 20 20 54 68 69 73 20 6d  e value.  This m
34a70 65 61 6e 73 20 74 68 61 74 20 61 6e 20 61 74 74  eans that an att
34a80 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20  empt is.** made 
34a90 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20 76  to convert the v
34aa0 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e 74 65 67  alue to an integ
34ab0 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70  er or floating p
34ac0 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63  oint.  If.** suc
34ad0 68 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  h a conversion i
34ae0 73 20 70 6f 73 73 69 62 6c 65 20 77 69 74 68 6f  s possible witho
34af0 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72  ut loss of infor
34b00 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72  mation (in other
34b10 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66 20 74 68  .** words, if th
34b20 65 20 76 61 6c 75 65 20 69 73 20 61 20 73 74 72  e value is a str
34b30 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c  ing that looks l
34b40 69 6b 65 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a  ike a number).**
34b50 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 76 65 72   then the conver
34b60 73 69 6f 6e 20 69 73 20 70 65 72 66 6f 72 6d 65  sion is performe
34b70 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 6e 6f  d.  Otherwise no
34b80 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75   conversion occu
34b90 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  rs..** The [SQLI
34ba0 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64 61 74  TE_INTEGER | dat
34bb0 61 74 79 70 65 5d 20 61 66 74 65 72 20 63 6f 6e  atype] after con
34bc0 76 65 72 73 69 6f 6e 20 69 73 20 72 65 74 75 72  version is retur
34bd0 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65  ned.)^.**.** Ple
34be0 61 73 65 20 70 61 79 20 70 61 72 74 69 63 75 6c  ase pay particul
34bf0 61 72 20 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20  ar attention to 
34c00 74 68 65 20 66 61 63 74 20 74 68 61 74 20 74 68  the fact that th
34c10 65 20 70 6f 69 6e 74 65 72 20 72 65 74 75 72 6e  e pointer return
34c20 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  ed.** from [sqli
34c30 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29  te3_value_blob()
34c40 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
34c50 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a  e_text()], or.**
34c60 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34c70 74 65 78 74 31 36 28 29 5d 20 63 61 6e 20 62 65  text16()] can be
34c80 20 69 6e 76 61 6c 69 64 61 74 65 64 20 62 79 20   invalidated by 
34c90 61 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  a subsequent cal
34ca0 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  l to.** [sqlite3
34cb0 5f 76 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c  _value_bytes()],
34cc0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
34cd0 62 79 74 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c  bytes16()], [sql
34ce0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
34cf0 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74  )],.** or [sqlit
34d00 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
34d10 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  )]..**.** These 
34d20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
34d30 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
34d40 20 73 61 6d 65 20 74 68 72 65 61 64 20 61 73 0a   same thread as.
34d50 2a 2a 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  ** the SQL funct
34d60 69 6f 6e 20 74 68 61 74 20 73 75 70 70 6c 69 65  ion that supplie
34d70 64 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  d the [sqlite3_v
34d80 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65 74 65 72  alue*] parameter
34d90 73 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  s..*/.SQLITE_API
34da0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c   const void *sql
34db0 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28  ite3_value_blob(
34dc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
34dd0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
34de0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
34df0 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  tes(sqlite3_valu
34e00 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
34e10 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
34e20 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  e_bytes16(sqlite
34e30 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
34e40 45 5f 41 50 49 20 64 6f 75 62 6c 65 20 73 71 6c  E_API double sql
34e50 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c  ite3_value_doubl
34e60 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
34e70 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
34e80 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
34e90 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
34ea0 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
34eb0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
34ec0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 36  lite3_value_int6
34ed0 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  4(sqlite3_value*
34ee0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
34ef0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
34f00 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
34f10 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
34f20 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
34f30 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
34f40 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
34f50 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
34f60 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  *);.SQLITE_API c
34f70 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
34f80 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
34f90 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
34fa0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  );.SQLITE_API co
34fb0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
34fc0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65  3_value_text16be
34fd0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
34fe0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  ;.SQLITE_API int
34ff0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
35000 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  ype(sqlite3_valu
35010 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  e*);.SQLITE_API 
35020 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
35030 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
35040 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
35050 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
35060 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
35070 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
35080 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
35090 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
350a0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
350b0 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
350c0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
350d0 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
350e0 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
350f0 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
35100 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
35110 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
35120 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
35130 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
35140 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
35150 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
35160 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
35170 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
35180 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
35190 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
351a0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
351b0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
351c0 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
351d0 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
351e0 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
351f0 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
35200 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
35210 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
35220 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
35230 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
35240 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
35250 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
35260 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
35270 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
35280 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
35290 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
352a0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
352b0 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
352c0 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
352d0 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
352e0 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
352f0 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
35300 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
35310 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
35320 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
35330 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
35340 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
35350 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
35360 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
35370 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
35380 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
35390 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
353a0 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
353b0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
353c0 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
353d0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
353e0 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
353f0 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
35400 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
35410 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
35420 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
35430 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
35440 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
35450 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65  er if N is.** le
35460 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
35470 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
35480 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
35490 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
354a0 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
354b0 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
354c0 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
354d0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
354e0 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
354f0 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
35500 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
35510 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
35520 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
35530 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
35540 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
35550 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
35560 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
35570 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
35580 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
35590 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
355a0 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
355b0 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
355c0 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  allocation.)^.**
355d0 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
355e0 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
355f0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
35600 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
35610 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
35620 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
35630 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
35640 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
35650 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
35660 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
35670 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
35680 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
35690 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
356a0 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
356b0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
356c0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
356d0 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
356e0 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
356f0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
35700 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
35710 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
35720 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
35730 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
35740 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
35750 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
35760 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
35770 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
35780 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ng..*/.SQLITE_AP
35790 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  I void *sqlite3_
357a0 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
357b0 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  t(sqlite3_contex
357c0 74 2a 2c 20 69 6e 74 20 6e 42 79 74 65 73 29 3b  t*, int nBytes);
357d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
357e0 3a 20 55 73 65 72 20 44 61 74 61 20 46 6f 72 20  : User Data For 
357f0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
35800 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 73 65  ^The sqlite3_use
35810 72 5f 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  r_data() interfa
35820 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
35830 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
35840 74 65 72 20 74 68 61 74 20 77 61 73 20 74 68 65  ter that was the
35850 20 70 55 73 65 72 44 61 74 61 20 70 61 72 61 6d   pUserData param
35860 65 74 65 72 20 28 74 68 65 20 35 74 68 20 70 61  eter (the 5th pa
35870 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
35880 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
35890 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
358a0 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
358b0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
358c0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
358d0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
358e0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
358f0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
35900 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ed function..**.
35910 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
35920 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
35930 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
35940 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
35950 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35960 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35970 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
35980 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
35990 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  *sqlite3_user_da
359a0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
359b0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
359c0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
359d0 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46  Connection For F
359e0 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e  unctions.**.** ^
359f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  The sqlite3_cont
35a00 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20  ext_db_handle() 
35a10 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
35a20 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74  s a copy of.** t
35a30 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68  he pointer to th
35a40 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
35a50 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74  ection] (the 1st
35a60 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f   parameter).** o
35a70 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  f the [sqlite3_c
35a80 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
35a90 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
35aa0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
35ab0 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20  n16()] routines 
35ac0 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a  that originally.
35ad0 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68  ** registered th
35ae0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65  e application de
35af0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a  fined function..
35b00 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71  */.SQLITE_API sq
35b10 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63  lite3 *sqlite3_c
35b20 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
35b30 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35b40 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
35b50 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75  REF: Function Au
35b60 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a  xiliary Data.**.
35b70 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  ** The following
35b80 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d   two functions m
35b90 61 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63  ay be used by sc
35ba0 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f  alar SQL functio
35bb0 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61  ns to.** associa
35bc0 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68  te metadata with
35bd0 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73   argument values
35be0 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61  . If the same va
35bf0 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f  lue is passed to
35c00 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76  .** multiple inv
35c10 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ocations of the 
35c20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  same SQL functio
35c30 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65  n during query e
35c40 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a  xecution, under.
35c50 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74  ** some circumst
35c60 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69  ances the associ
35c70 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61  ated metadata ma
35c80 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20  y be preserved. 
35c90 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75  This may.** be u
35ca0 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  sed, for example
35cb0 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c  , to add a regul
35cc0 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61  ar-expression ma
35cd0 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a  tching scalar.**
35ce0 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63   function. The c
35cf0 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20  ompiled version 
35d00 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65  of the regular e
35d10 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f  xpression is sto
35d20 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61  red as.** metada
35d30 74 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ta associated wi
35d40 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65  th the SQL value
35d50 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72   passed as the r
35d60 65 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f  egular expressio
35d70 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54  n.** pattern.  T
35d80 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
35d90 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
35da0 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
35db0 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
35dc0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
35dd0 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20  ame function so 
35de0 74 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61  that the origina
35df0 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  l pattern string
35e00 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  .** does not nee
35e10 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c  d to be recompil
35e20 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63  ed on each invoc
35e30 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
35e40 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  e sqlite3_get_au
35e50 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
35e60 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
35e70 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64  ter to the metad
35e80 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ata.** associate
35e90 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33  d by the sqlite3
35ea0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66  _set_auxdata() f
35eb0 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65  unction with the
35ec0 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a   Nth argument.**
35ed0 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70   value to the ap
35ee0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35ef0 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20  d function. ^If 
35f00 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20  no metadata has 
35f10 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65  been ever.** bee
35f20 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74  n set for the Nt
35f30 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68  h argument of th
35f40 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69  e function, or i
35f50 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  f the correspond
35f60 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ing.** function 
35f70 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68  parameter has ch
35f80 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20  anged since the 
35f90 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65  meta-data was se
35fa0 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74  t,.** then sqlit
35fb0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
35fc0 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20   returns a NULL 
35fd0 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  pointer..**.** ^
35fe0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f  The sqlite3_set_
35ff0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
36000 61 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65  ace saves the me
36010 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65  tadata.** pointe
36020 64 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20  d to by its 3rd 
36030 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65  parameter as the
36040 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68   metadata for th
36050 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65  e N-th.** argume
36060 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  nt of the applic
36070 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36080 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75  nction.  Subsequ
36090 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
360a0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
360b0 61 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75  ata() might retu
360c0 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66  rn this data, if
360d0 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62   it has.** not b
360e0 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  een destroyed..*
360f0 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20  * ^If it is not 
36100 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c  NULL, SQLite wil
36110 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
36120 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74  tructor.** funct
36130 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65  ion given by the
36140 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74   4th parameter t
36150 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  o sqlite3_set_au
36160 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68  xdata() on.** th
36170 65 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20  e metadata when 
36180 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
36190 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d  g function param
361a0 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20  eter changes.** 
361b0 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20  or when the SQL 
361c0 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65  statement comple
361d0 74 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63  tes, whichever c
361e0 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a  omes first..**.*
361f0 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65  * SQLite is free
36200 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73   to call the des
36210 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70  tructor and drop
36220 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79   metadata on any
36230 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66  .** parameter of
36240 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74   any function at
36250 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65   any time.  ^The
36260 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20   only guarantee 
36270 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64  is that.** the d
36280 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62  estructor will b
36290 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20  e called before 
362a0 74 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20  the metadata is 
362b0 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  dropped..**.** ^
362c0 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65  (In practice, me
362d0 74 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72  tadata is preser
362e0 76 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63  ved between func
362f0 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a  tion calls for.*
36300 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68  * expressions th
36310 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20  at are constant 
36320 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e  at compile time.
36330 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c   This includes l
36340 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73  iteral.** values
36350 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73   and [parameters
36360 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ].)^.**.** These
36370 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
36380 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
36390 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
363a0 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
363b0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
363c0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45  nning..*/.SQLITE
363d0 5f 41 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74  _API void *sqlit
363e0 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 73  e3_get_auxdata(s
363f0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
36400 20 69 6e 74 20 4e 29 3b 0a 53 51 4c 49 54 45 5f   int N);.SQLITE_
36410 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33  API void sqlite3
36420 5f 73 65 74 5f 61 75 78 64 61 74 61 28 73 71 6c  _set_auxdata(sql
36430 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
36440 6e 74 20 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69  nt N, void*, voi
36450 64 20 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a  d (*)(void*));..
36460 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
36470 20 43 6f 6e 73 74 61 6e 74 73 20 44 65 66 69 6e   Constants Defin
36480 69 6e 67 20 53 70 65 63 69 61 6c 20 44 65 73 74  ing Special Dest
36490 72 75 63 74 6f 72 20 42 65 68 61 76 69 6f 72 0a  ructor Behavior.
364a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20  **.** These are 
364b0 73 70 65 63 69 61 6c 20 76 61 6c 75 65 73 20 66  special values f
364c0 6f 72 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  or the destructo
364d0 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64  r that is passed
364e0 20 69 6e 20 61 73 20 74 68 65 0a 2a 2a 20 66 69   in as the.** fi
364f0 6e 61 6c 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  nal argument to 
36500 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73  routines like [s
36510 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
36520 6f 62 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 20  ob()].  ^If the 
36530 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72  destructor.** ar
36540 67 75 6d 65 6e 74 20 69 73 20 53 51 4c 49 54 45  gument is SQLITE
36550 5f 53 54 41 54 49 43 2c 20 69 74 20 6d 65 61 6e  _STATIC, it mean
36560 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
36570 6e 74 20 70 6f 69 6e 74 65 72 20 69 73 20 63 6f  nt pointer is co
36580 6e 73 74 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69  nstant.** and wi
36590 6c 6c 20 6e 65 76 65 72 20 63 68 61 6e 67 65 2e  ll never change.
365a0 20 20 49 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65    It does not ne
365b0 65 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79  ed to be destroy
365c0 65 64 2e 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c  ed.  ^The.** SQL
365d0 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 76 61  ITE_TRANSIENT va
365e0 6c 75 65 20 6d 65 61 6e 73 20 74 68 61 74 20 74  lue means that t
365f0 68 65 20 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20  he content will 
36600 6c 69 6b 65 6c 79 20 63 68 61 6e 67 65 20 69 6e  likely change in
36610 0a 2a 2a 20 74 68 65 20 6e 65 61 72 20 66 75 74  .** the near fut
36620 75 72 65 20 61 6e 64 20 74 68 61 74 20 53 51 4c  ure and that SQL
36630 69 74 65 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20  ite should make 
36640 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20  its own private 
36650 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63  copy of.** the c
36660 6f 6e 74 65 6e 74 20 62 65 66 6f 72 65 20 72 65  ontent before re
36670 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54  turning..**.** T
36680 68 65 20 74 79 70 65 64 65 66 20 69 73 20 6e 65  he typedef is ne
36690 63 65 73 73 61 72 79 20 74 6f 20 77 6f 72 6b 20  cessary to work 
366a0 61 72 6f 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20  around problems 
366b0 69 6e 20 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b  in certain.** C+
366c0 2b 20 63 6f 6d 70 69 6c 65 72 73 2e 20 20 53 65  + compilers.  Se
366d0 65 20 74 69 63 6b 65 74 20 23 32 31 39 31 2e 0a  e ticket #2191..
366e0 2a 2f 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20  */.typedef void 
366f0 28 2a 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  (*sqlite3_destru
36700 63 74 6f 72 5f 74 79 70 65 29 28 76 6f 69 64 2a  ctor_type)(void*
36710 29 3b 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  );.#define SQLIT
36720 45 5f 53 54 41 54 49 43 20 20 20 20 20 20 28 28  E_STATIC      ((
36730 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
36740 6f 72 5f 74 79 70 65 29 30 29 0a 23 64 65 66 69  or_type)0).#defi
36750 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ne SQLITE_TRANSI
36760 45 4e 54 20 20 20 28 28 73 71 6c 69 74 65 33 5f  ENT   ((sqlite3_
36770 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
36780 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  -1)../*.** CAPI3
36790 52 45 46 3a 20 53 65 74 74 69 6e 67 20 54 68 65  REF: Setting The
367a0 20 52 65 73 75 6c 74 20 4f 66 20 41 6e 20 53 51   Result Of An SQ
367b0 4c 20 46 75 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a  L Function.**.**
367c0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
367d0 61 72 65 20 75 73 65 64 20 62 79 20 74 68 65 20  are used by the 
367e0 78 46 75 6e 63 20 6f 72 20 78 46 69 6e 61 6c 20  xFunc or xFinal 
367f0 63 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 0a 2a  callbacks that.*
36800 2a 20 69 6d 70 6c 65 6d 65 6e 74 20 53 51 4c 20  * implement SQL 
36810 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
36820 67 72 65 67 61 74 65 73 2e 20 20 53 65 65 0a 2a  gregates.  See.*
36830 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  * [sqlite3_creat
36840 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
36850 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
36860 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
36870 2a 2a 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  ** for additiona
36880 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  l information..*
36890 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
368a0 69 6f 6e 73 20 77 6f 72 6b 20 76 65 72 79 20 6d  ions work very m
368b0 75 63 68 20 6c 69 6b 65 20 74 68 65 20 5b 70 61  uch like the [pa
368c0 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 5d  rameter binding]
368d0 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20 66 75   family of.** fu
368e0 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f 20  nctions used to 
368f0 62 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20 68  bind values to h
36900 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 69  ost parameters i
36910 6e 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  n prepared state
36920 6d 65 6e 74 73 2e 0a 2a 2a 20 52 65 66 65 72 20  ments..** Refer 
36930 74 6f 20 74 68 65 20 5b 53 51 4c 20 70 61 72 61  to the [SQL para
36940 6d 65 74 65 72 5d 20 64 6f 63 75 6d 65 6e 74 61  meter] documenta
36950 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69 6f  tion for additio
36960 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  nal information.
36970 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36980 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
36990 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
369a0 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
369b0 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
369c0 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
369d0 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 42 4c  ion to be the BL
369e0 4f 42 20 77 68 6f 73 65 20 63 6f 6e 74 65 6e 74  OB whose content
369f0 20 69 73 20 70 6f 69 6e 74 65 64 0a 2a 2a 20 74   is pointed.** t
36a00 6f 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20  o by the second 
36a10 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 77 68  parameter and wh
36a20 69 63 68 20 69 73 20 4e 20 62 79 74 65 73 20 6c  ich is N bytes l
36a30 6f 6e 67 20 77 68 65 72 65 20 4e 20 69 73 20 74  ong where N is t
36a40 68 65 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61  he.** third para
36a50 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
36a60 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36a70 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 69 6e 74 65  _zeroblob() inte
36a80 72 66 61 63 65 73 20 73 65 74 20 74 68 65 20 72  rfaces set the r
36a90 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20  esult of.** the 
36aa0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36ab0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
36ac0 62 65 20 61 20 42 4c 4f 42 20 63 6f 6e 74 61 69  be a BLOB contai
36ad0 6e 69 6e 67 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a  ning all zero.**
36ae0 20 62 79 74 65 73 20 61 6e 64 20 4e 20 62 79 74   bytes and N byt
36af0 65 73 20 69 6e 20 73 69 7a 65 2c 20 77 68 65 72  es in size, wher
36b00 65 20 4e 20 69 73 20 74 68 65 20 76 61 6c 75 65  e N is the value
36b10 20 6f 66 20 74 68 65 20 32 6e 64 20 70 61 72 61   of the 2nd para
36b20 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
36b30 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
36b40 5f 64 6f 75 62 6c 65 28 29 20 69 6e 74 65 72 66  _double() interf
36b50 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
36b60 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
36b70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
36b80 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
36b90 65 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  e a floating poi
36ba0 6e 74 20 76 61 6c 75 65 20 73 70 65 63 69 66 69  nt value specifi
36bb0 65 64 0a 2a 2a 20 62 79 20 69 74 73 20 32 6e 64  ed.** by its 2nd
36bc0 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
36bd0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36be0 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
36bf0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36c00 65 72 72 6f 72 31 36 28 29 20 66 75 6e 63 74 69  error16() functi
36c10 6f 6e 73 0a 2a 2a 20 63 61 75 73 65 20 74 68 65  ons.** cause the
36c20 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 53 51 4c   implemented SQL
36c30 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 74 68 72   function to thr
36c40 6f 77 20 61 6e 20 65 78 63 65 70 74 69 6f 6e 2e  ow an exception.
36c50 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
36c60 20 74 68 65 20 73 74 72 69 6e 67 20 70 6f 69 6e   the string poin
36c70 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a 2a  ted to by the.**
36c80 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
36c90 66 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  f sqlite3_result
36ca0 5f 65 72 72 6f 72 28 29 20 6f 72 20 73 71 6c 69  _error() or sqli
36cb0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
36cc0 31 36 28 29 0a 2a 2a 20 61 73 20 74 68 65 20 74  16().** as the t
36cd0 65 78 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20  ext of an error 
36ce0 6d 65 73 73 61 67 65 2e 20 20 5e 53 51 4c 69 74  message.  ^SQLit
36cf0 65 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  e interprets the
36d00 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
36d10 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
36d20 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
36d30 6f 72 28 29 20 61 73 20 55 54 46 2d 38 2e 20 5e  or() as UTF-8. ^
36d40 53 51 4c 69 74 65 0a 2a 2a 20 69 6e 74 65 72 70  SQLite.** interp
36d50 72 65 74 73 20 74 68 65 20 73 74 72 69 6e 67 20  rets the string 
36d60 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
36d70 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 61 73  ult_error16() as
36d80 20 55 54 46 2d 31 36 20 69 6e 20 6e 61 74 69 76   UTF-16 in nativ
36d90 65 0a 2a 2a 20 62 79 74 65 20 6f 72 64 65 72 2e  e.** byte order.
36da0 20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20    ^If the third 
36db0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
36dc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
36dd0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
36de0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
36df0 28 29 20 69 73 20 6e 65 67 61 74 69 76 65 20 74  () is negative t
36e00 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73  hen SQLite takes
36e10 20 61 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   as the error.**
36e20 20 6d 65 73 73 61 67 65 20 61 6c 6c 20 74 65 78   message all tex
36e30 74 20 75 70 20 74 68 72 6f 75 67 68 20 74 68 65  t up through the
36e40 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
36e50 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
36e60 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
36e70 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
36e80 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72 0a 2a  ult_error() or.*
36e90 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
36ea0 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 6f  _error16() is no
36eb0 6e 2d 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  n-negative then 
36ec0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74 68 61  SQLite takes tha
36ed0 74 20 6d 61 6e 79 0a 2a 2a 20 62 79 74 65 73 20  t many.** bytes 
36ee0 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29  (not characters)
36ef0 20 66 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61   from the 2nd pa
36f00 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 65  rameter as the e
36f10 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
36f20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
36f30 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 6e 64  sult_error() and
36f40 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
36f50 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 72 6f 75  error16().** rou
36f60 74 69 6e 65 73 20 6d 61 6b 65 20 61 20 70 72 69  tines make a pri
36f70 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65  vate copy of the
36f80 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 74   error message t
36f90 65 78 74 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ext before.** th
36fa0 65 79 20 72 65 74 75 72 6e 2e 20 20 48 65 6e 63  ey return.  Henc
36fb0 65 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 20 66  e, the calling f
36fc0 75 6e 63 74 69 6f 6e 20 63 61 6e 20 64 65 61 6c  unction can deal
36fd0 6c 6f 63 61 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64  locate or.** mod
36fe0 69 66 79 20 74 68 65 20 74 65 78 74 20 61 66 74  ify the text aft
36ff0 65 72 20 74 68 65 79 20 72 65 74 75 72 6e 20 77  er they return w
37000 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
37010 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37020 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 29  ult_error_code()
37030 20 66 75 6e 63 74 69 6f 6e 20 63 68 61 6e 67 65   function change
37040 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64 65  s the error code
37050 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
37060 53 51 4c 69 74 65 20 61 73 20 61 20 72 65 73 75  SQLite as a resu
37070 6c 74 20 6f 66 20 61 6e 20 65 72 72 6f 72 20 69  lt of an error i
37080 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 20 20 5e  n a function.  ^
37090 42 79 20 64 65 66 61 75 6c 74 2c 0a 2a 2a 20 74  By default,.** t
370a0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73  he error code is
370b0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 20 20   SQLITE_ERROR.  
370c0 5e 41 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  ^A subsequent ca
370d0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  ll to sqlite3_re
370e0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
370f0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
37100 74 5f 65 72 72 6f 72 31 36 28 29 20 72 65 73 65  t_error16() rese
37110 74 73 20 74 68 65 20 65 72 72 6f 72 20 63 6f 64  ts the error cod
37120 65 20 74 6f 20 53 51 4c 49 54 45 5f 45 52 52 4f  e to SQLITE_ERRO
37130 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  R..**.** ^The sq
37140 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
37150 6f 72 5f 74 6f 6f 62 69 67 28 29 20 69 6e 74 65  or_toobig() inte
37160 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
37170 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
37180 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
37190 69 6e 67 20 74 68 61 74 20 61 20 73 74 72 69 6e  ing that a strin
371a0 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74 6f 6f  g or BLOB is too
371b0 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65 73 65   long to represe
371c0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
371d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
371e0 72 6f 72 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ror_nomem() inte
371f0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
37200 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 0a  ite to throw an.
37210 2a 2a 20 65 72 72 6f 72 20 69 6e 64 69 63 61 74  ** error indicat
37220 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
37230 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
37240 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
37250 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
37260 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
37270 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
37280 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
37290 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
372a0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
372b0 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
372c0 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
372d0 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
372e0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
372f0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37300 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
37310 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
37320 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
37330 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
37340 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
37350 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
37360 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
37370 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
37380 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
37390 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
373a0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
373b0 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
373c0 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
373d0 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
373e0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
373f0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
37400 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
37410 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
37420 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
37430 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
37440 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
37450 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
37460 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
37470 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
37480 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
37490 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
374a0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
374b0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
374c0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
374d0 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
374e0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
374f0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
37500 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
37510 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
37520 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
37530 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
37540 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
37550 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
37560 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
37570 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
37580 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
37590 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
375a0 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
375b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
375c0 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
375d0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
375e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
375f0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
37600 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
37610 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
37620 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
37630 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
37640 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
37650 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
37660 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
37670 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
37680 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
37690 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
376a0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
376b0 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
376c0 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
376d0 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
376e0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
376f0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
37700 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
37710 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
37720 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
37730 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
37740 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
37750 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74  on result.  If t
37760 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
37770 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
37780 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73  , then it.** mus
37790 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
377a0 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74  fset into the st
377b0 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e  ring where the N
377c0 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
377d0 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66  uld.** appear if
377e0 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
377f0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64  e NUL terminated
37800 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
37810 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a  aracters occur.*
37820 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  * in the string 
37830 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74  at a byte offset
37840 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68   that is less th
37850 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  an the value of 
37860 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d  the 3rd.** param
37870 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  eter, then the r
37880 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
37890 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62  will contain emb
378a0 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74  edded NULs and t
378b0 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20  he.** result of 
378c0 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72  expressions oper
378d0 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73  ating on strings
378e0 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
378f0 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
37900 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
37910 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
37920 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37930 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
37940 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
37950 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
37960 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
37970 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
37980 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
37990 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
379a0 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
379b0 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
379c0 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
379d0 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
379e0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
379f0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
37a00 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
37a10 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
37a20 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
37a30 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
37a40 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
37a50 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
37a60 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
37a70 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
37a80 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
37a90 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
37aa0 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
37ab0 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
37ac0 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
37ad0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
37ae0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
37af0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
37b00 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
37b10 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
37b20 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
37b30 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
37b40 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
37b50 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
37b60 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
37b70 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
37b80 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
37b90 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
37ba0 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
37bb0 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
37bc0 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
37bd0 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
37be0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
37bf0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
37c00 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
37c10 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
37c20 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
37c30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
37c40 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
37c50 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
37c60 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
37c70 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
37c80 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
37c90 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
37ca0 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
37cb0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
37cc0 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
37cd0 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
37ce0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
37cf0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
37d00 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
37d10 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
37d20 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
37d30 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
37d40 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
37d50 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
37d60 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
37d70 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
37d80 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
37d90 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
37da0 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
37db0 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
37dc0 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
37dd0 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
37de0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
37df0 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
37e00 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
37e10 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
37e20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
37e30 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
37e40 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
37e50 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
37e60 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
37e70 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
37e80 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
37e90 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
37ea0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
37eb0 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
37ec0 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
37ed0 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
37ee0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
37ef0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
37f00 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
37f10 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
37f20 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
37f30 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
37f40 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
37f50 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
37f60 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
37f70 65 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74  esult_blob(sqlit
37f80 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
37f90 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76  st void*, int, v
37fa0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
37fb0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
37fc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
37fd0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
37fe0 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
37ff0 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
38000 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38010 65 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f  error(sqlite3_co
38020 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68  ntext*, const ch
38030 61 72 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  ar*, int);.SQLIT
38040 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
38050 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
38060 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  6(sqlite3_contex
38070 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
38080 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
38090 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  I void sqlite3_r
380a0 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
380b0 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
380c0 78 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  xt*);.SQLITE_API
380d0 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
380e0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
380f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
38100 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76  *);.SQLITE_API v
38110 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
38120 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65 28 73 71  lt_error_code(sq
38130 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
38140 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  int);.SQLITE_API
38150 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65   void sqlite3_re
38160 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33  sult_int(sqlite3
38170 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b  _context*, int);
38180 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64  .SQLITE_API void
38190 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
381a0 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 63 6f  int64(sqlite3_co
381b0 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f  ntext*, sqlite3_
381c0 69 6e 74 36 34 29 3b 0a 53 51 4c 49 54 45 5f 41  int64);.SQLITE_A
381d0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
381e0 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69  result_null(sqli
381f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53  te3_context*);.S
38200 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
38210 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
38220 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt(sqlite3_conte
38230 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  xt*, const char*
38240 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
38250 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54 45 5f 41  oid*));.SQLITE_A
38260 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
38270 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73 71  result_text16(sq
38280 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20  lite3_context*, 
38290 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
382a0 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
382b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
382c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
382d0 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74  t_text16le(sqlit
382e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
382f0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f  st void*, int,vo
38300 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 53  id(*)(void*));.S
38310 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
38320 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
38330 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
38340 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
38350 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
38360 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
38370 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74  E_API void sqlit
38380 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
38390 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
383a0 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
383b0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f  );.SQLITE_API vo
383c0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
383d0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
383e0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
383f0 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
38400 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
38410 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
38420 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
38430 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
38440 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
38450 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
38460 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
38470 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
38480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
38490 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
384a0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
384b0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
384c0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
384d0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
384e0 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
384f0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
38500 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
38510 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
38520 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
38530 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
38540 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
38550 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
38560 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
38570 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
38580 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
38590 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
385a0 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
385b0 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
385c0 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
385d0 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
385e0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
385f0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
38600 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
38610 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
38620 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
38630 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
38640 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
38650 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
38660 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
38670 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
38680 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
38690 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
386a0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
386b0 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
386c0 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
386d0 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
386e0 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
386f0 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
38700 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
38710 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
38720 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
38730 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
38740 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
38750 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
38760 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
38770 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
38780 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
38790 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
387a0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
387b0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
387c0 45