System.Data.SQLite
Hex Artifact Content
Not logged in

Artifact 02048d73c018088970c2d97910fe82bf4d71db09:


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 36 2e 20 20  ersion 3.7.16.  
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 23 69 66 20 64 65 66 69 6e 65  ndif..#if define
2840: 64 28 5f 5f 4f 70 65 6e 42 53 44 5f 5f 29 20 26  d(__OpenBSD__) &
2850: 26 20 21 64 65 66 69 6e 65 64 28 5f 42 53 44 5f  & !defined(_BSD_
2860: 53 4f 55 52 43 45 29 0a 23 20 64 65 66 69 6e 65  SOURCE).# define
2870: 20 5f 42 53 44 5f 53 4f 55 52 43 45 0a 23 65 6e   _BSD_SOURCE.#en
2880: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 6e 63 6c 75  dif../*.** Inclu
2890: 64 65 20 73 74 61 6e 64 61 72 64 20 68 65 61 64  de standard head
28a0: 65 72 20 66 69 6c 65 73 20 61 73 20 6e 65 63 65  er files as nece
28b0: 73 73 61 72 79 0a 2a 2f 0a 23 69 66 64 65 66 20  ssary.*/.#ifdef 
28c0: 48 41 56 45 5f 53 54 44 49 4e 54 5f 48 0a 23 69  HAVE_STDINT_H.#i
28d0: 6e 63 6c 75 64 65 20 3c 73 74 64 69 6e 74 2e 68  nclude <stdint.h
28e0: 3e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65 66 20  >.#endif.#ifdef 
28f0: 48 41 56 45 5f 49 4e 54 54 59 50 45 53 5f 48 0a  HAVE_INTTYPES_H.
2900: 23 69 6e 63 6c 75 64 65 20 3c 69 6e 74 74 79 70  #include <inttyp
2910: 65 73 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a  es.h>.#endif../*
2920: 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e  .** The followin
2930: 67 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73 65  g macros are use
2940: 64 20 74 6f 20 63 61 73 74 20 70 6f 69 6e 74 65  d to cast pointe
2950: 72 73 20 74 6f 20 69 6e 74 65 67 65 72 73 20 61  rs to integers a
2960: 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 74  nd.** integers t
2970: 6f 20 70 6f 69 6e 74 65 72 73 2e 20 20 54 68 65  o pointers.  The
2980: 20 77 61 79 20 79 6f 75 20 64 6f 20 74 68 69 73   way you do this
2990: 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65   varies from one
29a0: 20 63 6f 6d 70 69 6c 65 72 0a 2a 2a 20 74 6f 20   compiler.** to 
29b0: 74 68 65 20 6e 65 78 74 2c 20 73 6f 20 77 65 20  the next, so we 
29c0: 68 61 76 65 20 64 65 76 65 6c 6f 70 65 64 20 74  have developed t
29d0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 65 74  he following set
29e0: 20 6f 66 20 23 69 66 20 73 74 61 74 65 6d 65 6e   of #if statemen
29f0: 74 73 0a 2a 2a 20 74 6f 20 67 65 6e 65 72 61 74  ts.** to generat
2a00: 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 6d 61  e appropriate ma
2a10: 63 72 6f 73 20 66 6f 72 20 61 20 77 69 64 65 20  cros for a wide 
2a20: 72 61 6e 67 65 20 6f 66 20 63 6f 6d 70 69 6c 65  range of compile
2a30: 72 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f  rs..**.** The co
2a40: 72 72 65 63 74 20 22 41 4e 53 49 22 20 77 61 79  rrect "ANSI" way
2a50: 20 74 6f 20 64 6f 20 74 68 69 73 20 69 73 20 74   to do this is t
2a60: 6f 20 75 73 65 20 74 68 65 20 69 6e 74 70 74 72  o use the intptr
2a70: 5f 74 20 74 79 70 65 2e 20 0a 2a 2a 20 55 6e 66  _t type. .** Unf
2a80: 6f 72 74 75 6e 61 74 65 6c 79 2c 20 74 68 61 74  ortunately, that
2a90: 20 74 79 70 65 64 65 66 20 69 73 20 6e 6f 74 20   typedef is not 
2aa0: 61 76 61 69 6c 61 62 6c 65 20 6f 6e 20 61 6c 6c  available on all
2ab0: 20 63 6f 6d 70 69 6c 65 72 73 2c 20 6f 72 0a 2a   compilers, or.*
2ac0: 2a 20 69 66 20 69 74 20 69 73 20 61 76 61 69 6c  * if it is avail
2ad0: 61 62 6c 65 2c 20 69 74 20 72 65 71 75 69 72 65  able, it require
2ae0: 73 20 61 6e 20 23 69 6e 63 6c 75 64 65 20 6f 66  s an #include of
2af0: 20 73 70 65 63 69 66 69 63 20 68 65 61 64 65 72   specific header
2b00: 73 0a 2a 2a 20 74 68 61 74 20 76 61 72 79 20 66  s.** that vary f
2b10: 72 6f 6d 20 6f 6e 65 20 6d 61 63 68 69 6e 65 20  rom one machine 
2b20: 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2a 0a  to the next..**.
2b30: 2a 2a 20 54 69 63 6b 65 74 20 23 33 38 36 30 3a  ** Ticket #3860:
2b40: 20 20 54 68 65 20 6c 6c 76 6d 2d 67 63 63 2d 34    The llvm-gcc-4
2b50: 2e 32 20 63 6f 6d 70 69 6c 65 72 20 66 72 6f 6d  .2 compiler from
2b60: 20 41 70 70 6c 65 20 63 68 6f 6b 65 73 20 6f 6e   Apple chokes on
2b70: 0a 2a 2a 20 74 68 65 20 28 28 76 6f 69 64 2a 29  .** the ((void*)
2b80: 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 20  &((char*)0)[X]) 
2b90: 63 6f 6e 73 74 72 75 63 74 2e 20 20 42 75 74 20  construct.  But 
2ba0: 4d 53 56 43 20 63 68 6f 6b 65 73 20 6f 6e 20 28  MSVC chokes on (
2bb0: 28 76 6f 69 64 2a 29 28 58 29 29 2e 0a 2a 2a 20  (void*)(X))..** 
2bc0: 53 6f 20 77 65 20 68 61 76 65 20 74 6f 20 64 65  So we have to de
2bd0: 66 69 6e 65 20 74 68 65 20 6d 61 63 72 6f 73 20  fine the macros 
2be0: 69 6e 20 64 69 66 66 65 72 65 6e 74 20 77 61 79  in different way
2bf0: 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  s depending on t
2c00: 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 72 2e 0a  he.** compiler..
2c10: 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64 28 5f  */.#if defined(_
2c20: 5f 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29  _PTRDIFF_TYPE__)
2c30: 20 20 2f 2a 20 54 68 69 73 20 63 61 73 65 20 73    /* This case s
2c40: 68 6f 75 6c 64 20 77 6f 72 6b 20 66 6f 72 20 47  hould work for G
2c50: 43 43 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20 53  CC */.# define S
2c60: 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54 52  QLITE_INT_TO_PTR
2c70: 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 5f 5f  (X)  ((void*)(__
2c80: 50 54 52 44 49 46 46 5f 54 59 50 45 5f 5f 29 28  PTRDIFF_TYPE__)(
2c90: 58 29 29 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  X)).# define SQL
2ca0: 49 54 45 5f 50 54 52 5f 54 4f 5f 49 4e 54 28 58  ITE_PTR_TO_INT(X
2cb0: 29 20 20 28 28 69 6e 74 29 28 5f 5f 50 54 52 44  )  ((int)(__PTRD
2cc0: 49 46 46 5f 54 59 50 45 5f 5f 29 28 58 29 29 0a  IFF_TYPE__)(X)).
2cd0: 23 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 5f  #elif !defined(_
2ce0: 5f 47 4e 55 43 5f 5f 29 20 20 20 20 20 20 20 2f  _GNUC__)       /
2cf0: 2a 20 57 6f 72 6b 73 20 66 6f 72 20 63 6f 6d 70  * Works for comp
2d00: 69 6c 65 72 73 20 6f 74 68 65 72 20 74 68 61 6e  ilers other than
2d10: 20 4c 4c 56 4d 20 2a 2f 0a 23 20 64 65 66 69 6e   LLVM */.# defin
2d20: 65 20 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f  e SQLITE_INT_TO_
2d30: 50 54 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29  PTR(X)  ((void*)
2d40: 26 28 28 63 68 61 72 2a 29 30 29 5b 58 5d 29 0a  &((char*)0)[X]).
2d50: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2d60: 50 54 52 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28  PTR_TO_INT(X)  (
2d70: 28 69 6e 74 29 28 28 28 63 68 61 72 2a 29 58 29  (int)(((char*)X)
2d80: 2d 28 63 68 61 72 2a 29 30 29 29 0a 23 65 6c 69  -(char*)0)).#eli
2d90: 66 20 64 65 66 69 6e 65 64 28 48 41 56 45 5f 53  f defined(HAVE_S
2da0: 54 44 49 4e 54 5f 48 29 20 20 20 2f 2a 20 55 73  TDINT_H)   /* Us
2db0: 65 20 74 68 69 73 20 63 61 73 65 20 69 66 20 77  e this case if w
2dc0: 65 20 68 61 76 65 20 41 4e 53 49 20 68 65 61 64  e have ANSI head
2dd0: 65 72 73 20 2a 2f 0a 23 20 64 65 66 69 6e 65 20  ers */.# define 
2de0: 53 51 4c 49 54 45 5f 49 4e 54 5f 54 4f 5f 50 54  SQLITE_INT_TO_PT
2df0: 52 28 58 29 20 20 28 28 76 6f 69 64 2a 29 28 69  R(X)  ((void*)(i
2e00: 6e 74 70 74 72 5f 74 29 28 58 29 29 0a 23 20 64  ntptr_t)(X)).# d
2e10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52  efine SQLITE_PTR
2e20: 5f 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e  _TO_INT(X)  ((in
2e30: 74 29 28 69 6e 74 70 74 72 5f 74 29 28 58 29 29  t)(intptr_t)(X))
2e40: 0a 23 65 6c 73 65 20 20 20 20 20 20 20 20 20 20  .#else          
2e50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
2e60: 2f 2a 20 47 65 6e 65 72 61 74 65 73 20 61 20 77  /* Generates a w
2e70: 61 72 6e 69 6e 67 20 2d 20 62 75 74 20 69 74 20  arning - but it 
2e80: 61 6c 77 61 79 73 20 77 6f 72 6b 73 20 2a 2f 0a  always works */.
2e90: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
2ea0: 49 4e 54 5f 54 4f 5f 50 54 52 28 58 29 20 20 28  INT_TO_PTR(X)  (
2eb0: 28 76 6f 69 64 2a 29 28 58 29 29 0a 23 20 64 65  (void*)(X)).# de
2ec0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 54 52 5f  fine SQLITE_PTR_
2ed0: 54 4f 5f 49 4e 54 28 58 29 20 20 28 28 69 6e 74  TO_INT(X)  ((int
2ee0: 29 28 58 29 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a  )(X)).#endif../*
2ef0: 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 54  .** The SQLITE_T
2f00: 48 52 45 41 44 53 41 46 45 20 6d 61 63 72 6f 20  HREADSAFE macro 
2f10: 6d 75 73 74 20 62 65 20 64 65 66 69 6e 65 64 20  must be defined 
2f20: 61 73 20 30 2c 20 31 2c 20 6f 72 20 32 2e 0a 2a  as 0, 1, or 2..*
2f30: 2a 20 30 20 6d 65 61 6e 73 20 6d 75 74 65 78 65  * 0 means mutexe
2f40: 73 20 61 72 65 20 70 65 72 6d 61 6e 65 6e 74 6c  s are permanentl
2f50: 79 20 64 69 73 61 62 6c 65 20 61 6e 64 20 74 68  y disable and th
2f60: 65 20 6c 69 62 72 61 72 79 20 69 73 20 6e 65 76  e library is nev
2f70: 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 61 66 65  er.** threadsafe
2f80: 2e 20 20 31 20 6d 65 61 6e 73 20 74 68 65 20 6c  .  1 means the l
2f90: 69 62 72 61 72 79 20 69 73 20 73 65 72 69 61 6c  ibrary is serial
2fa0: 69 7a 65 64 20 77 68 69 63 68 20 69 73 20 74 68  ized which is th
2fb0: 65 20 68 69 67 68 65 73 74 0a 2a 2a 20 6c 65 76  e highest.** lev
2fc0: 65 6c 20 6f 66 20 74 68 72 65 61 64 73 61 66 65  el of threadsafe
2fd0: 74 79 2e 20 20 32 20 6d 65 61 6e 73 20 74 68 65  ty.  2 means the
2fe0: 20 6c 69 62 61 72 79 20 69 73 20 6d 75 6c 74 69   libary is multi
2ff0: 74 68 72 65 61 64 65 64 20 2d 20 6d 75 6c 74 69  threaded - multi
3000: 70 6c 65 0a 2a 2a 20 74 68 72 65 61 64 73 20 63  ple.** threads c
3010: 61 6e 20 75 73 65 20 53 51 4c 69 74 65 20 61 73  an use SQLite as
3020: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
3030: 74 68 72 65 61 64 73 20 74 72 79 20 74 6f 20 75  threads try to u
3040: 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64  se the same.** d
3050: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3060: 6f 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  on at the same t
3070: 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 4f 6c 64 65 72  ime..**.** Older
3080: 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
3090: 69 74 65 20 75 73 65 64 20 61 6e 20 6f 70 74 69  ite used an opti
30a0: 6f 6e 61 6c 20 54 48 52 45 41 44 53 41 46 45 20  onal THREADSAFE 
30b0: 6d 61 63 72 6f 2e 0a 2a 2a 20 57 65 20 73 75 70  macro..** We sup
30c0: 70 6f 72 74 20 74 68 61 74 20 66 6f 72 20 6c 65  port that for le
30d0: 67 61 63 79 2e 0a 2a 2f 0a 23 69 66 20 21 64 65  gacy..*/.#if !de
30e0: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 54 48 52  fined(SQLITE_THR
30f0: 45 41 44 53 41 46 45 29 0a 23 69 66 20 64 65 66  EADSAFE).#if def
3100: 69 6e 65 64 28 54 48 52 45 41 44 53 41 46 45 29  ined(THREADSAFE)
3110: 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
3120: 5f 54 48 52 45 41 44 53 41 46 45 20 54 48 52 45  _THREADSAFE THRE
3130: 41 44 53 41 46 45 0a 23 65 6c 73 65 0a 23 20 64  ADSAFE.#else.# d
3140: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 48 52  efine SQLITE_THR
3150: 45 41 44 53 41 46 45 20 31 20 2f 2a 20 49 4d 50  EADSAFE 1 /* IMP
3160: 3a 20 52 2d 30 37 32 37 32 2d 32 32 33 30 39 20  : R-07272-22309 
3170: 2a 2f 0a 23 65 6e 64 69 66 0a 23 65 6e 64 69 66  */.#endif.#endif
3180: 0a 0a 2f 2a 0a 2a 2a 20 50 6f 77 65 72 73 61 66  ../*.** Powersaf
3190: 65 20 6f 76 65 72 77 72 69 74 65 20 69 73 20 6f  e overwrite is o
31a0: 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 42  n by default.  B
31b0: 75 74 20 63 61 6e 20 62 65 20 74 75 72 6e 65 64  ut can be turned
31c0: 20 6f 66 66 20 75 73 69 6e 67 0a 2a 2a 20 74 68   off using.** th
31d0: 65 20 2d 44 53 51 4c 49 54 45 5f 50 4f 57 45 52  e -DSQLITE_POWER
31e0: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 3d 30  SAFE_OVERWRITE=0
31f0: 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 6f 70   command-line op
3200: 74 69 6f 6e 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66  tion..*/.#ifndef
3210: 20 53 51 4c 49 54 45 5f 50 4f 57 45 52 53 41 46   SQLITE_POWERSAF
3220: 45 5f 4f 56 45 52 57 52 49 54 45 0a 23 20 64 65  E_OVERWRITE.# de
3230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 4f 57 45  fine SQLITE_POWE
3240: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
3250: 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20  1.#endif../*.** 
3260: 54 68 65 20 53 51 4c 49 54 45 5f 44 45 46 41 55  The SQLITE_DEFAU
3270: 4c 54 5f 4d 45 4d 53 54 41 54 55 53 20 6d 61 63  LT_MEMSTATUS mac
3280: 72 6f 20 6d 75 73 74 20 62 65 20 64 65 66 69 6e  ro must be defin
3290: 65 64 20 61 73 20 65 69 74 68 65 72 20 30 20 6f  ed as either 0 o
32a0: 72 20 31 2e 0a 2a 2a 20 49 74 20 64 65 74 65 72  r 1..** It deter
32b0: 6d 69 6e 65 73 20 77 68 65 74 68 65 72 20 6f 72  mines whether or
32c0: 20 6e 6f 74 20 74 68 65 20 66 65 61 74 75 72 65   not the feature
32d0: 73 20 72 65 6c 61 74 65 64 20 74 6f 20 0a 2a 2a  s related to .**
32e0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
32f0: 45 4d 53 54 41 54 55 53 20 61 72 65 20 61 76 61  EMSTATUS are ava
3300: 69 6c 61 62 6c 65 20 62 79 20 64 65 66 61 75 6c  ilable by defaul
3310: 74 20 6f 72 20 6e 6f 74 2e 20 54 68 69 73 20 76  t or not. This v
3320: 61 6c 75 65 20 63 61 6e 0a 2a 2a 20 62 65 20 6f  alue can.** be o
3330: 76 65 72 72 69 64 64 65 6e 20 61 74 20 72 75 6e  verridden at run
3340: 74 69 6d 65 20 75 73 69 6e 67 20 74 68 65 20 73  time using the s
3350: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
3360: 41 50 49 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66  API..*/.#if !def
3370: 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 46 41  ined(SQLITE_DEFA
3380: 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 29 0a 23  ULT_MEMSTATUS).#
3390: 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44   define SQLITE_D
33a0: 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53  EFAULT_MEMSTATUS
33b0: 20 31 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a   1.#endif../*.**
33c0: 20 45 78 61 63 74 6c 79 20 6f 6e 65 20 6f 66 20   Exactly one of 
33d0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 6d 61  the following ma
33e0: 63 72 6f 73 20 6d 75 73 74 20 62 65 20 64 65 66  cros must be def
33f0: 69 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f  ined in order to
3400: 0a 2a 2a 20 73 70 65 63 69 66 79 20 77 68 69 63  .** specify whic
3410: 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  h memory allocat
3420: 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 74 6f  ion subsystem to
3430: 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 20 20 20 20   use..**.**     
3440: 53 51 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41  SQLITE_SYSTEM_MA
3450: 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 20 2f 2f  LLOC          //
3460: 20 55 73 65 20 6e 6f 72 6d 61 6c 20 73 79 73 74   Use normal syst
3470: 65 6d 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 20 20  em malloc().**  
3480: 20 20 20 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f     SQLITE_WIN32_
3490: 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20 20  MALLOC          
34a0: 20 2f 2f 20 55 73 65 20 57 69 6e 33 32 20 6e 61   // Use Win32 na
34b0: 74 69 76 65 20 68 65 61 70 20 41 50 49 0a 2a 2a  tive heap API.**
34c0: 20 20 20 20 20 53 51 4c 49 54 45 5f 5a 45 52 4f       SQLITE_ZERO
34d0: 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 20  _MALLOC         
34e0: 20 20 20 2f 2f 20 55 73 65 20 61 20 73 74 75 62     // Use a stub
34f0: 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20   allocator that 
3500: 61 6c 77 61 79 73 20 66 61 69 6c 73 0a 2a 2a 20  always fails.** 
3510: 20 20 20 20 53 51 4c 49 54 45 5f 4d 45 4d 44 45      SQLITE_MEMDE
3520: 42 55 47 20 20 20 20 20 20 20 20 20 20 20 20 20  BUG             
3530: 20 20 2f 2f 20 44 65 62 75 67 67 69 6e 67 20 76    // Debugging v
3540: 65 72 73 69 6f 6e 20 6f 66 20 73 79 73 74 65 6d  ersion of system
3550: 20 6d 61 6c 6c 6f 63 28 29 0a 2a 2a 0a 2a 2a 20   malloc().**.** 
3560: 4f 6e 20 57 69 6e 64 6f 77 73 2c 20 69 66 20 74  On Windows, if t
3570: 68 65 20 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  he SQLITE_WIN32_
3580: 4d 41 4c 4c 4f 43 5f 56 41 4c 49 44 41 54 45 20  MALLOC_VALIDATE 
3590: 6d 61 63 72 6f 20 69 73 20 64 65 66 69 6e 65 64  macro is defined
35a0: 20 61 6e 64 20 74 68 65 0a 2a 2a 20 61 73 73 65   and the.** asse
35b0: 72 74 28 29 20 6d 61 63 72 6f 20 69 73 20 65 6e  rt() macro is en
35c0: 61 62 6c 65 64 2c 20 65 61 63 68 20 63 61 6c 6c  abled, each call
35d0: 20 69 6e 74 6f 20 74 68 65 20 57 69 6e 33 32 20   into the Win32 
35e0: 6e 61 74 69 76 65 20 68 65 61 70 20 73 75 62 73  native heap subs
35f0: 79 73 74 65 6d 0a 2a 2a 20 77 69 6c 6c 20 63 61  ystem.** will ca
3600: 75 73 65 20 48 65 61 70 56 61 6c 69 64 61 74 65  use HeapValidate
3610: 20 74 6f 20 62 65 20 63 61 6c 6c 65 64 2e 20 20   to be called.  
3620: 49 66 20 68 65 61 70 20 76 61 6c 69 64 61 74 69  If heap validati
3630: 6f 6e 20 73 68 6f 75 6c 64 20 66 61 69 6c 2c 20  on should fail, 
3640: 61 6e 0a 2a 2a 20 61 73 73 65 72 74 69 6f 6e 20  an.** assertion 
3650: 77 69 6c 6c 20 62 65 20 74 72 69 67 67 65 72 65  will be triggere
3660: 64 2e 0a 2a 2a 0a 2a 2a 20 28 48 69 73 74 6f 72  d..**.** (Histor
3670: 69 63 61 6c 20 6e 6f 74 65 3a 20 20 54 68 65 72  ical note:  Ther
3680: 65 20 75 73 65 64 20 74 6f 20 62 65 20 73 65 76  e used to be sev
3690: 65 72 61 6c 20 6f 74 68 65 72 20 6f 70 74 69 6f  eral other optio
36a0: 6e 73 2c 20 62 75 74 20 77 65 27 76 65 0a 2a 2a  ns, but we've.**
36b0: 20 70 61 72 65 64 20 69 74 20 64 6f 77 6e 20 74   pared it down t
36c0: 6f 20 6a 75 73 74 20 74 68 65 73 65 20 74 68 72  o just these thr
36d0: 65 65 2e 29 0a 2a 2a 0a 2a 2a 20 49 66 20 6e 6f  ee.).**.** If no
36e0: 6e 65 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ne of the above 
36f0: 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65  are defined, the
3700: 6e 20 73 65 74 20 53 51 4c 49 54 45 5f 53 59 53  n set SQLITE_SYS
3710: 54 45 4d 5f 4d 41 4c 4c 4f 43 20 61 73 0a 2a 2a  TEM_MALLOC as.**
3720: 20 74 68 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2f   the default..*/
3730: 0a 23 69 66 20 64 65 66 69 6e 65 64 28 53 51 4c  .#if defined(SQL
3740: 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f  ITE_SYSTEM_MALLO
3750: 43 29 20 5c 0a 20 20 2b 20 64 65 66 69 6e 65 64  C) \.  + defined
3760: 28 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41  (SQLITE_WIN32_MA
3770: 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65 66 69  LLOC) \.  + defi
3780: 6e 65 64 28 53 51 4c 49 54 45 5f 5a 45 52 4f 5f  ned(SQLITE_ZERO_
3790: 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64 65  MALLOC) \.  + de
37a0: 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 4d 45 4d  fined(SQLITE_MEM
37b0: 44 45 42 55 47 29 3e 31 0a 23 20 65 72 72 6f 72  DEBUG)>1.# error
37c0: 20 22 54 77 6f 20 6f 72 20 6d 6f 72 65 20 6f 66   "Two or more of
37d0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63   the following c
37e0: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 63 6f 6e 66  ompile-time conf
37f0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
3800: 73 5c 0a 20 61 72 65 20 64 65 66 69 6e 65 64 20  s\. are defined 
3810: 62 75 74 20 61 74 20 6d 6f 73 74 20 6f 6e 65 20  but at most one 
3820: 69 73 20 61 6c 6c 6f 77 65 64 3a 5c 0a 20 53 51  is allowed:\. SQ
3830: 4c 49 54 45 5f 53 59 53 54 45 4d 5f 4d 41 4c 4c  LITE_SYSTEM_MALL
3840: 4f 43 2c 20 53 51 4c 49 54 45 5f 57 49 4e 33 32  OC, SQLITE_WIN32
3850: 5f 4d 41 4c 4c 4f 43 2c 20 53 51 4c 49 54 45 5f  _MALLOC, SQLITE_
3860: 4d 45 4d 44 45 42 55 47 2c 5c 0a 20 53 51 4c 49  MEMDEBUG,\. SQLI
3870: 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 22 0a  TE_ZERO_MALLOC".
3880: 23 65 6e 64 69 66 0a 23 69 66 20 64 65 66 69 6e  #endif.#if defin
3890: 65 64 28 53 51 4c 49 54 45 5f 53 59 53 54 45 4d  ed(SQLITE_SYSTEM
38a0: 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20 2b 20 64  _MALLOC) \.  + d
38b0: 65 66 69 6e 65 64 28 53 51 4c 49 54 45 5f 57 49  efined(SQLITE_WI
38c0: 4e 33 32 5f 4d 41 4c 4c 4f 43 29 20 5c 0a 20 20  N32_MALLOC) \.  
38d0: 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45  + defined(SQLITE
38e0: 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 29 20 5c 0a  _ZERO_MALLOC) \.
38f0: 20 20 2b 20 64 65 66 69 6e 65 64 28 53 51 4c 49    + defined(SQLI
3900: 54 45 5f 4d 45 4d 44 45 42 55 47 29 3d 3d 30 0a  TE_MEMDEBUG)==0.
3910: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
3920: 53 59 53 54 45 4d 5f 4d 41 4c 4c 4f 43 20 31 0a  SYSTEM_MALLOC 1.
3930: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 49 66  #endif../*.** If
3940: 20 53 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53   SQLITE_MALLOC_S
3950: 4f 46 54 5f 4c 49 4d 49 54 20 69 73 20 6e 6f 74  OFT_LIMIT is not
3960: 20 7a 65 72 6f 2c 20 74 68 65 6e 20 74 72 79 20   zero, then try 
3970: 74 6f 20 6b 65 65 70 20 74 68 65 0a 2a 2a 20 73  to keep the.** s
3980: 69 7a 65 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61  izes of memory a
3990: 6c 6c 6f 63 61 74 69 6f 6e 73 20 62 65 6c 6f 77  llocations below
39a0: 20 74 68 69 73 20 76 61 6c 75 65 20 77 68 65 72   this value wher
39b0: 65 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2f 0a 23  e possible..*/.#
39c0: 69 66 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49  if !defined(SQLI
39d0: 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46 54 5f 4c  TE_MALLOC_SOFT_L
39e0: 49 4d 49 54 29 0a 23 20 64 65 66 69 6e 65 20 53  IMIT).# define S
39f0: 51 4c 49 54 45 5f 4d 41 4c 4c 4f 43 5f 53 4f 46  QLITE_MALLOC_SOF
3a00: 54 5f 4c 49 4d 49 54 20 31 30 32 34 0a 23 65 6e  T_LIMIT 1024.#en
3a10: 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 57 65 20 6e 65  dif../*.** We ne
3a20: 65 64 20 74 6f 20 64 65 66 69 6e 65 20 5f 58 4f  ed to define _XO
3a30: 50 45 4e 5f 53 4f 55 52 43 45 20 61 73 20 66 6f  PEN_SOURCE as fo
3a40: 6c 6c 6f 77 73 20 69 6e 20 6f 72 64 65 72 20 74  llows in order t
3a50: 6f 20 65 6e 61 62 6c 65 0a 2a 2a 20 72 65 63 75  o enable.** recu
3a60: 72 73 69 76 65 20 6d 75 74 65 78 65 73 20 6f 6e  rsive mutexes on
3a70: 20 6d 6f 73 74 20 55 6e 69 78 20 73 79 73 74 65   most Unix syste
3a80: 6d 73 2e 20 20 42 75 74 20 4d 61 63 20 4f 53 20  ms.  But Mac OS 
3a90: 58 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 0a  X is different..
3aa0: 2a 2a 20 54 68 65 20 5f 58 4f 50 45 4e 5f 53 4f  ** The _XOPEN_SO
3ab0: 55 52 43 45 20 64 65 66 69 6e 65 20 63 61 75 73  URCE define caus
3ac0: 65 73 20 70 72 6f 62 6c 65 6d 73 20 66 6f 72 20  es problems for 
3ad0: 4d 61 63 20 4f 53 20 58 20 77 65 20 61 72 65 20  Mac OS X we are 
3ae0: 74 6f 6c 64 2c 0a 2a 2a 20 73 6f 20 69 74 20 69  told,.** so it i
3af0: 73 20 6f 6d 69 74 74 65 64 20 74 68 65 72 65 2e  s omitted there.
3b00: 20 20 53 65 65 20 74 69 63 6b 65 74 20 23 32 36    See ticket #26
3b10: 37 33 2e 0a 2a 2a 0a 2a 2a 20 4c 61 74 65 72 20  73..**.** Later 
3b20: 77 65 20 6c 65 61 72 6e 20 74 68 61 74 20 5f 58  we learn that _X
3b30: 4f 50 45 4e 5f 53 4f 55 52 43 45 20 69 73 20 70  OPEN_SOURCE is p
3b40: 6f 6f 72 6c 79 20 6f 72 20 69 6e 63 6f 72 72 65  oorly or incorre
3b50: 63 74 6c 79 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  ctly.** implemen
3b60: 74 65 64 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  ted on some syst
3b70: 65 6d 73 2e 20 20 53 6f 20 77 65 20 61 76 6f 69  ems.  So we avoi
3b80: 64 20 64 65 66 69 6e 69 6e 67 20 69 74 20 61 74  d defining it at
3b90: 20 61 6c 6c 0a 2a 2a 20 69 66 20 69 74 20 69 73   all.** if it is
3ba0: 20 61 6c 72 65 61 64 79 20 64 65 66 69 6e 65 64   already defined
3bb0: 20 6f 72 20 69 66 20 69 74 20 69 73 20 75 6e 6e   or if it is unn
3bc0: 65 65 64 65 64 20 62 65 63 61 75 73 65 20 77 65  eeded because we
3bd0: 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 64 6f 69 6e   are.** not doin
3be0: 67 20 61 20 74 68 72 65 61 64 73 61 66 65 20 62  g a threadsafe b
3bf0: 75 69 6c 64 2e 20 20 54 69 63 6b 65 74 20 23 32  uild.  Ticket #2
3c00: 36 38 31 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  681..**.** See a
3c10: 6c 73 6f 20 74 69 63 6b 65 74 20 23 32 37 34 31  lso ticket #2741
3c20: 2e 0a 2a 2f 0a 23 69 66 20 21 64 65 66 69 6e 65  ..*/.#if !define
3c30: 64 28 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 29  d(_XOPEN_SOURCE)
3c40: 20 26 26 20 21 64 65 66 69 6e 65 64 28 5f 5f 44   && !defined(__D
3c50: 41 52 57 49 4e 5f 5f 29 20 5c 0a 20 26 26 20 21  ARWIN__) \. && !
3c60: 64 65 66 69 6e 65 64 28 5f 5f 41 50 50 4c 45 5f  defined(__APPLE_
3c70: 5f 29 20 26 26 20 53 51 4c 49 54 45 5f 54 48 52  _) && SQLITE_THR
3c80: 45 41 44 53 41 46 45 0a 23 20 20 64 65 66 69 6e  EADSAFE.#  defin
3c90: 65 20 5f 58 4f 50 45 4e 5f 53 4f 55 52 43 45 20  e _XOPEN_SOURCE 
3ca0: 35 30 30 20 20 2f 2a 20 4e 65 65 64 65 64 20 74  500  /* Needed t
3cb0: 6f 20 65 6e 61 62 6c 65 20 70 74 68 72 65 61 64  o enable pthread
3cc0: 20 72 65 63 75 72 73 69 76 65 20 6d 75 74 65 78   recursive mutex
3cd0: 65 73 20 2a 2f 0a 23 65 6e 64 69 66 0a 0a 2f 2a  es */.#endif../*
3ce0: 0a 2a 2a 20 54 68 65 20 54 43 4c 20 68 65 61 64  .** The TCL head
3cf0: 65 72 73 20 61 72 65 20 6f 6e 6c 79 20 6e 65 65  ers are only nee
3d00: 64 65 64 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69  ded when compili
3d10: 6e 67 20 74 68 65 20 54 43 4c 20 62 69 6e 64 69  ng the TCL bindi
3d20: 6e 67 73 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69  ngs..*/.#if defi
3d30: 6e 65 64 28 53 51 4c 49 54 45 5f 54 43 4c 29 20  ned(SQLITE_TCL) 
3d40: 7c 7c 20 64 65 66 69 6e 65 64 28 54 43 4c 53 48  || defined(TCLSH
3d50: 29 0a 23 20 69 6e 63 6c 75 64 65 20 3c 74 63 6c  ).# include <tcl
3d60: 2e 68 3e 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .h>.#endif../*.*
3d70: 2a 20 4e 44 45 42 55 47 20 61 6e 64 20 53 51 4c  * NDEBUG and SQL
3d80: 49 54 45 5f 44 45 42 55 47 20 61 72 65 20 6f 70  ITE_DEBUG are op
3d90: 70 6f 73 69 74 65 73 2e 20 20 49 74 20 73 68 6f  posites.  It sho
3da0: 75 6c 64 20 61 6c 77 61 79 73 20 62 65 20 74 72  uld always be tr
3db0: 75 65 20 74 68 61 74 0a 2a 2a 20 64 65 66 69 6e  ue that.** defin
3dc0: 65 64 28 4e 44 45 42 55 47 29 3d 3d 21 64 65 66  ed(NDEBUG)==!def
3dd0: 69 6e 65 64 28 53 51 4c 49 54 45 5f 44 45 42 55  ined(SQLITE_DEBU
3de0: 47 29 2e 20 20 49 66 20 74 68 69 73 20 69 73 20  G).  If this is 
3df0: 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 74 72  not currently tr
3e00: 75 65 2c 0a 2a 2a 20 6d 61 6b 65 20 69 74 20 74  ue,.** make it t
3e10: 72 75 65 20 62 79 20 64 65 66 69 6e 69 6e 67 20  rue by defining 
3e20: 6f 72 20 75 6e 64 65 66 69 6e 69 6e 67 20 4e 44  or undefining ND
3e30: 45 42 55 47 2e 0a 2a 2a 0a 2a 2a 20 53 65 74 74  EBUG..**.** Sett
3e40: 69 6e 67 20 4e 44 45 42 55 47 20 6d 61 6b 65 73  ing NDEBUG makes
3e50: 20 74 68 65 20 63 6f 64 65 20 73 6d 61 6c 6c 65   the code smalle
3e60: 72 20 61 6e 64 20 72 75 6e 20 66 61 73 74 65 72  r and run faster
3e70: 20 62 79 20 64 69 73 61 62 6c 69 6e 67 20 74 68   by disabling th
3e80: 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 61 73 73 65  e.** number asse
3e90: 72 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20  rt() statements 
3ea0: 69 6e 20 74 68 65 20 63 6f 64 65 2e 20 20 53 6f  in the code.  So
3eb0: 20 77 65 20 77 61 6e 74 20 74 68 65 20 64 65 66   we want the def
3ec0: 61 75 6c 74 20 61 63 74 69 6f 6e 0a 2a 2a 20 74  ault action.** t
3ed0: 6f 20 62 65 20 66 6f 72 20 4e 44 45 42 55 47 20  o be for NDEBUG 
3ee0: 74 6f 20 62 65 20 73 65 74 20 61 6e 64 20 4e 44  to be set and ND
3ef0: 45 42 55 47 20 74 6f 20 62 65 20 75 6e 64 65 66  EBUG to be undef
3f00: 69 6e 65 64 20 6f 6e 6c 79 20 69 66 20 53 51 4c  ined only if SQL
3f10: 49 54 45 5f 44 45 42 55 47 0a 2a 2a 20 69 73 20  ITE_DEBUG.** is 
3f20: 73 65 74 2e 20 20 54 68 75 73 20 4e 44 45 42 55  set.  Thus NDEBU
3f30: 47 20 62 65 63 6f 6d 65 73 20 61 6e 20 6f 70 74  G becomes an opt
3f40: 2d 69 6e 20 72 61 74 68 65 72 20 74 68 61 6e 20  -in rather than 
3f50: 61 6e 20 6f 70 74 2d 6f 75 74 0a 2a 2a 20 66 65  an opt-out.** fe
3f60: 61 74 75 72 65 2e 0a 2a 2f 0a 23 69 66 20 21 64  ature..*/.#if !d
3f70: 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29 20 26  efined(NDEBUG) &
3f80: 26 20 21 64 65 66 69 6e 65 64 28 53 51 4c 49 54  & !defined(SQLIT
3f90: 45 5f 44 45 42 55 47 29 20 0a 23 20 64 65 66 69  E_DEBUG) .# defi
3fa0: 6e 65 20 4e 44 45 42 55 47 20 31 0a 23 65 6e 64  ne NDEBUG 1.#end
3fb0: 69 66 0a 23 69 66 20 64 65 66 69 6e 65 64 28 4e  if.#if defined(N
3fc0: 44 45 42 55 47 29 20 26 26 20 64 65 66 69 6e 65  DEBUG) && define
3fd0: 64 28 53 51 4c 49 54 45 5f 44 45 42 55 47 29 0a  d(SQLITE_DEBUG).
3fe0: 23 20 75 6e 64 65 66 20 4e 44 45 42 55 47 0a 23  # undef NDEBUG.#
3ff0: 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65  endif../*.** The
4000: 20 74 65 73 74 63 61 73 65 28 29 20 6d 61 63 72   testcase() macr
4010: 6f 20 69 73 20 75 73 65 64 20 74 6f 20 61 69 64  o is used to aid
4020: 20 69 6e 20 63 6f 76 65 72 61 67 65 20 74 65 73   in coverage tes
4030: 74 69 6e 67 2e 20 20 57 68 65 6e 20 0a 2a 2a 20  ting.  When .** 
4040: 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74  doing coverage t
4050: 65 73 74 69 6e 67 2c 20 74 68 65 20 63 6f 6e 64  esting, the cond
4060: 69 74 69 6f 6e 20 69 6e 73 69 64 65 20 74 68 65  ition inside the
4070: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
4080: 74 65 73 74 63 61 73 65 28 29 20 6d 75 73 74 20  testcase() must 
4090: 62 65 20 65 76 61 6c 75 61 74 65 64 20 62 6f 74  be evaluated bot
40a0: 68 20 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65  h true and false
40b0: 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20   in order to.** 
40c0: 67 65 74 20 66 75 6c 6c 20 62 72 61 6e 63 68 20  get full branch 
40d0: 63 6f 76 65 72 61 67 65 2e 20 20 54 68 65 20 74  coverage.  The t
40e0: 65 73 74 63 61 73 65 28 29 20 6d 61 63 72 6f 20  estcase() macro 
40f0: 69 73 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 74  is inserted.** t
4100: 6f 20 68 65 6c 70 20 65 6e 73 75 72 65 20 61 64  o help ensure ad
4110: 65 71 75 61 74 65 20 74 65 73 74 20 63 6f 76 65  equate test cove
4120: 72 61 67 65 20 69 6e 20 70 6c 61 63 65 73 20 77  rage in places w
4130: 68 65 72 65 20 73 69 6d 70 6c 65 0a 2a 2a 20 63  here simple.** c
4140: 6f 6e 64 69 74 69 6f 6e 2f 64 65 63 69 73 69 6f  ondition/decisio
4150: 6e 20 63 6f 76 65 72 61 67 65 20 69 73 20 69 6e  n coverage is in
4160: 61 64 65 71 75 61 74 65 2e 20 20 46 6f 72 20 65  adequate.  For e
4170: 78 61 6d 70 6c 65 2c 20 74 65 73 74 63 61 73 65  xample, testcase
4180: 28 29 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  ().** can be use
4190: 64 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 62  d to make sure b
41a0: 6f 75 6e 64 61 72 79 20 76 61 6c 75 65 73 20 61  oundary values a
41b0: 72 65 20 74 65 73 74 65 64 2e 20 20 46 6f 72 0a  re tested.  For.
41c0: 2a 2a 20 62 69 74 6d 61 73 6b 20 74 65 73 74 73  ** bitmask tests
41d0: 2c 20 74 65 73 74 63 61 73 65 28 29 20 63 61 6e  , testcase() can
41e0: 20 62 65 20 75 73 65 64 20 74 6f 20 6d 61 6b 65   be used to make
41f0: 20 73 75 72 65 20 65 61 63 68 20 62 69 74 0a 2a   sure each bit.*
4200: 2a 20 69 73 20 73 69 67 6e 69 66 69 63 61 6e 74  * is significant
4210: 20 61 6e 64 20 75 73 65 64 20 61 74 20 6c 65 61   and used at lea
4220: 73 74 20 6f 6e 63 65 2e 20 20 4f 6e 20 73 77 69  st once.  On swi
4230: 74 63 68 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  tch statements.*
4240: 2a 20 77 68 65 72 65 20 6d 75 6c 74 69 70 6c 65  * where multiple
4250: 20 63 61 73 65 73 20 67 6f 20 74 6f 20 74 68 65   cases go to the
4260: 20 73 61 6d 65 20 62 6c 6f 63 6b 20 6f 66 20 63   same block of c
4270: 6f 64 65 2c 20 74 65 73 74 63 61 73 65 28 29 0a  ode, testcase().
4280: 2a 2a 20 63 61 6e 20 69 6e 73 75 72 65 20 74 68  ** can insure th
4290: 61 74 20 61 6c 6c 20 63 61 73 65 73 20 61 72 65  at all cases are
42a0: 20 65 76 61 6c 75 61 74 65 64 2e 0a 2a 2a 0a 2a   evaluated..**.*
42b0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
42c0: 43 4f 56 45 52 41 47 45 5f 54 45 53 54 0a 53 51  COVERAGE_TEST.SQ
42d0: 4c 49 54 45 5f 50 52 49 56 41 54 45 20 20 20 76  LITE_PRIVATE   v
42e0: 6f 69 64 20 73 71 6c 69 74 65 33 43 6f 76 65 72  oid sqlite3Cover
42f0: 61 67 65 28 69 6e 74 29 3b 0a 23 20 64 65 66 69  age(int);.# defi
4300: 6e 65 20 74 65 73 74 63 61 73 65 28 58 29 20 20  ne testcase(X)  
4310: 69 66 28 20 58 20 29 7b 20 73 71 6c 69 74 65 33  if( X ){ sqlite3
4320: 43 6f 76 65 72 61 67 65 28 5f 5f 4c 49 4e 45 5f  Coverage(__LINE_
4330: 5f 29 3b 20 7d 0a 23 65 6c 73 65 0a 23 20 64 65  _); }.#else.# de
4340: 66 69 6e 65 20 74 65 73 74 63 61 73 65 28 58 29  fine testcase(X)
4350: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54  .#endif../*.** T
4360: 68 65 20 54 45 53 54 4f 4e 4c 59 20 6d 61 63 72  he TESTONLY macr
4370: 6f 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 63  o is used to enc
4380: 6c 6f 73 65 20 76 61 72 69 61 62 6c 65 20 64 65  lose variable de
4390: 63 6c 61 72 61 74 69 6f 6e 73 20 6f 72 0a 2a 2a  clarations or.**
43a0: 20 6f 74 68 65 72 20 62 69 74 73 20 6f 66 20 63   other bits of c
43b0: 6f 64 65 20 74 68 61 74 20 61 72 65 20 6e 65 65  ode that are nee
43c0: 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 74  ded to support t
43d0: 68 65 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20  he arguments.** 
43e0: 77 69 74 68 69 6e 20 74 65 73 74 63 61 73 65 28  within testcase(
43f0: 29 20 61 6e 64 20 61 73 73 65 72 74 28 29 20 6d  ) and assert() m
4400: 61 63 72 6f 73 2e 0a 2a 2f 0a 23 69 66 20 21 64  acros..*/.#if !d
4410: 65 66 69 6e 65 64 28 4e 44 45 42 55 47 29 20 7c  efined(NDEBUG) |
4420: 7c 20 64 65 66 69 6e 65 64 28 53 51 4c 49 54 45  | defined(SQLITE
4430: 5f 43 4f 56 45 52 41 47 45 5f 54 45 53 54 29 0a  _COVERAGE_TEST).
4440: 23 20 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c  # define TESTONL
4450: 59 28 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20  Y(X)  X.#else.# 
4460: 64 65 66 69 6e 65 20 54 45 53 54 4f 4e 4c 59 28  define TESTONLY(
4470: 58 29 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  X).#endif../*.**
4480: 20 53 6f 6d 65 74 69 6d 65 73 20 77 65 20 6e 65   Sometimes we ne
4490: 65 64 20 61 20 73 6d 61 6c 6c 20 61 6d 6f 75 6e  ed a small amoun
44a0: 74 20 6f 66 20 63 6f 64 65 20 73 75 63 68 20 61  t of code such a
44b0: 73 20 61 20 76 61 72 69 61 62 6c 65 20 69 6e 69  s a variable ini
44c0: 74 69 61 6c 69 7a 61 74 69 6f 6e 0a 2a 2a 20 74  tialization.** t
44d0: 6f 20 73 65 74 75 70 20 66 6f 72 20 61 20 6c 61  o setup for a la
44e0: 74 65 72 20 61 73 73 65 72 74 28 29 20 73 74 61  ter assert() sta
44f0: 74 65 6d 65 6e 74 2e 20 20 57 65 20 64 6f 20 6e  tement.  We do n
4500: 6f 74 20 77 61 6e 74 20 74 68 69 73 20 63 6f 64  ot want this cod
4510: 65 20 74 6f 0a 2a 2a 20 61 70 70 65 61 72 20 77  e to.** appear w
4520: 68 65 6e 20 61 73 73 65 72 74 28 29 20 69 73 20  hen assert() is 
4530: 64 69 73 61 62 6c 65 64 2e 20 20 54 68 65 20 66  disabled.  The f
4540: 6f 6c 6c 6f 77 69 6e 67 20 6d 61 63 72 6f 20 69  ollowing macro i
4550: 73 20 74 68 65 72 65 66 6f 72 65 0a 2a 2a 20 75  s therefore.** u
4560: 73 65 64 20 74 6f 20 63 6f 6e 74 61 69 6e 20 74  sed to contain t
4570: 68 61 74 20 73 65 74 75 70 20 63 6f 64 65 2e 20  hat setup code. 
4580: 20 54 68 65 20 22 56 56 41 22 20 61 63 72 6f 6e   The "VVA" acron
4590: 79 6d 20 73 74 61 6e 64 73 20 66 6f 72 0a 2a 2a  ym stands for.**
45a0: 20 22 56 65 72 69 66 69 63 61 74 69 6f 6e 2c 20   "Verification, 
45b0: 56 61 6c 69 64 61 74 69 6f 6e 2c 20 61 6e 64 20  Validation, and 
45c0: 41 63 63 72 65 64 69 74 61 74 69 6f 6e 22 2e 20  Accreditation". 
45d0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
45e0: 20 74 68 65 0a 2a 2a 20 63 6f 64 65 20 77 69 74   the.** code wit
45f0: 68 69 6e 20 56 56 41 5f 4f 4e 4c 59 28 29 20 77  hin VVA_ONLY() w
4600: 69 6c 6c 20 6f 6e 6c 79 20 72 75 6e 20 64 75 72  ill only run dur
4610: 69 6e 67 20 76 65 72 69 66 69 63 61 74 69 6f 6e  ing verification
4620: 20 70 72 6f 63 65 73 73 65 73 2e 0a 2a 2f 0a 23   processes..*/.#
4630: 69 66 6e 64 65 66 20 4e 44 45 42 55 47 0a 23 20  ifndef NDEBUG.# 
4640: 64 65 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28  define VVA_ONLY(
4650: 58 29 20 20 58 0a 23 65 6c 73 65 0a 23 20 64 65  X)  X.#else.# de
4660: 66 69 6e 65 20 56 56 41 5f 4f 4e 4c 59 28 58 29  fine VVA_ONLY(X)
4670: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54  .#endif../*.** T
4680: 68 65 20 41 4c 57 41 59 53 20 61 6e 64 20 4e 45  he ALWAYS and NE
4690: 56 45 52 20 6d 61 63 72 6f 73 20 73 75 72 72 6f  VER macros surro
46a0: 75 6e 64 20 62 6f 6f 6c 65 61 6e 20 65 78 70 72  und boolean expr
46b0: 65 73 73 69 6f 6e 73 20 77 68 69 63 68 20 0a 2a  essions which .*
46c0: 2a 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  * are intended t
46d0: 6f 20 61 6c 77 61 79 73 20 62 65 20 74 72 75 65  o always be true
46e0: 20 6f 72 20 66 61 6c 73 65 2c 20 72 65 73 70 65   or false, respe
46f0: 63 74 69 76 65 6c 79 2e 20 20 53 75 63 68 0a 2a  ctively.  Such.*
4700: 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f  * expressions co
4710: 75 6c 64 20 62 65 20 6f 6d 69 74 74 65 64 20 66  uld be omitted f
4720: 72 6f 6d 20 74 68 65 20 63 6f 64 65 20 63 6f 6d  rom the code com
4730: 70 6c 65 74 65 6c 79 2e 20 20 42 75 74 20 74 68  pletely.  But th
4740: 65 79 0a 2a 2a 20 61 72 65 20 69 6e 63 6c 75 64  ey.** are includ
4750: 65 64 20 69 6e 20 61 20 66 65 77 20 63 61 73 65  ed in a few case
4760: 73 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  s in order to en
4770: 68 61 6e 63 65 20 74 68 65 20 72 65 73 69 6c 69  hance the resili
4780: 65 6e 63 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ence.** of SQLit
4790: 65 20 74 6f 20 75 6e 65 78 70 65 63 74 65 64 20  e to unexpected 
47a0: 62 65 68 61 76 69 6f 72 20 2d 20 74 6f 20 6d 61  behavior - to ma
47b0: 6b 65 20 74 68 65 20 63 6f 64 65 20 22 73 65 6c  ke the code "sel
47c0: 66 2d 68 65 61 6c 69 6e 67 22 0a 2a 2a 20 6f 72  f-healing".** or
47d0: 20 22 64 75 63 74 69 6c 65 22 20 72 61 74 68 65   "ductile" rathe
47e0: 72 20 74 68 61 6e 20 62 65 69 6e 67 20 22 62 72  r than being "br
47f0: 69 74 74 6c 65 22 20 61 6e 64 20 63 72 61 73 68  ittle" and crash
4800: 69 6e 67 20 61 74 20 74 68 65 20 66 69 72 73 74  ing at the first
4810: 0a 2a 2a 20 68 69 6e 74 20 6f 66 20 75 6e 70 6c  .** hint of unpl
4820: 61 6e 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  anned behavior..
4830: 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77  **.** In other w
4840: 6f 72 64 73 2c 20 41 4c 57 41 59 53 20 61 6e 64  ords, ALWAYS and
4850: 20 4e 45 56 45 52 20 61 72 65 20 61 64 64 65 64   NEVER are added
4860: 20 66 6f 72 20 64 65 66 65 6e 73 69 76 65 20 63   for defensive c
4870: 6f 64 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  ode..**.** When 
4880: 64 6f 69 6e 67 20 63 6f 76 65 72 61 67 65 20 74  doing coverage t
4890: 65 73 74 69 6e 67 20 41 4c 57 41 59 53 20 61 6e  esting ALWAYS an
48a0: 64 20 4e 45 56 45 52 20 61 72 65 20 68 61 72 64  d NEVER are hard
48b0: 2d 63 6f 64 65 64 20 74 6f 0a 2a 2a 20 62 65 20  -coded to.** be 
48c0: 74 72 75 65 20 61 6e 64 20 66 61 6c 73 65 20 73  true and false s
48d0: 6f 20 74 68 61 74 20 74 68 65 20 75 6e 72 65 61  o that the unrea
48e0: 63 68 61 62 6c 65 20 63 6f 64 65 20 74 68 65 6e  chable code then
48f0: 20 73 70 65 63 69 66 79 20 77 69 6c 6c 0a 2a 2a   specify will.**
4900: 20 6e 6f 74 20 62 65 20 63 6f 75 6e 74 65 64 20   not be counted 
4910: 61 73 20 75 6e 74 65 73 74 65 64 20 63 6f 64 65  as untested code
4920: 2e 0a 2a 2f 0a 23 69 66 20 64 65 66 69 6e 65 64  ..*/.#if defined
4930: 28 53 51 4c 49 54 45 5f 43 4f 56 45 52 41 47 45  (SQLITE_COVERAGE
4940: 5f 54 45 53 54 29 0a 23 20 64 65 66 69 6e 65 20  _TEST).# define 
4950: 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28  ALWAYS(X)      (
4960: 31 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56 45  1).# define NEVE
4970: 52 28 58 29 20 20 20 20 20 20 20 28 30 29 0a 23  R(X)       (0).#
4980: 65 6c 69 66 20 21 64 65 66 69 6e 65 64 28 4e 44  elif !defined(ND
4990: 45 42 55 47 29 0a 23 20 64 65 66 69 6e 65 20 41  EBUG).# define A
49a0: 4c 57 41 59 53 28 58 29 20 20 20 20 20 20 28 28  LWAYS(X)      ((
49b0: 58 29 3f 31 3a 28 61 73 73 65 72 74 28 30 29 2c  X)?1:(assert(0),
49c0: 30 29 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56  0)).# define NEV
49d0: 45 52 28 58 29 20 20 20 20 20 20 20 28 28 58 29  ER(X)       ((X)
49e0: 3f 28 61 73 73 65 72 74 28 30 29 2c 31 29 3a 30  ?(assert(0),1):0
49f0: 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  ).#else.# define
4a00: 20 41 4c 57 41 59 53 28 58 29 20 20 20 20 20 20   ALWAYS(X)      
4a10: 28 58 29 0a 23 20 64 65 66 69 6e 65 20 4e 45 56  (X).# define NEV
4a20: 45 52 28 58 29 20 20 20 20 20 20 20 28 58 29 0a  ER(X)       (X).
4a30: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 52 65  #endif../*.** Re
4a40: 74 75 72 6e 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  turn true (non-z
4a50: 65 72 6f 29 20 69 66 20 74 68 65 20 69 6e 70 75  ero) if the inpu
4a60: 74 20 69 73 20 61 20 69 6e 74 65 67 65 72 20 74  t is a integer t
4a70: 68 61 74 20 69 73 20 74 6f 6f 20 6c 61 72 67 65  hat is too large
4a80: 0a 2a 2a 20 74 6f 20 66 69 74 20 69 6e 20 33 32  .** to fit in 32
4a90: 2d 62 69 74 73 2e 20 20 54 68 69 73 20 6d 61 63  -bits.  This mac
4aa0: 72 6f 20 69 73 20 75 73 65 64 20 69 6e 73 69 64  ro is used insid
4ab0: 65 20 6f 66 20 76 61 72 69 6f 75 73 20 74 65 73  e of various tes
4ac0: 74 63 61 73 65 28 29 0a 2a 2a 20 6d 61 63 72 6f  tcase().** macro
4ad0: 73 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  s to verify that
4ae0: 20 77 65 20 68 61 76 65 20 74 65 73 74 65 64 20   we have tested 
4af0: 53 51 4c 69 74 65 20 66 6f 72 20 6c 61 72 67 65  SQLite for large
4b00: 2d 66 69 6c 65 20 73 75 70 70 6f 72 74 2e 0a 2a  -file support..*
4b10: 2f 0a 23 64 65 66 69 6e 65 20 49 53 5f 42 49 47  /.#define IS_BIG
4b20: 5f 49 4e 54 28 58 29 20 20 28 28 28 58 29 26 7e  _INT(X)  (((X)&~
4b30: 28 69 36 34 29 30 78 66 66 66 66 66 66 66 66 29  (i64)0xffffffff)
4b40: 21 3d 30 29 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  !=0)../*.** The 
4b50: 6d 61 63 72 6f 20 75 6e 6c 69 6b 65 6c 79 28 29  macro unlikely()
4b60: 20 69 73 20 61 20 68 69 6e 74 20 74 68 61 74 20   is a hint that 
4b70: 73 75 72 72 6f 75 6e 64 73 20 61 20 62 6f 6f 6c  surrounds a bool
4b80: 65 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f  ean.** expressio
4b90: 6e 20 74 68 61 74 20 69 73 20 75 73 75 61 6c 6c  n that is usuall
4ba0: 79 20 66 61 6c 73 65 2e 20 20 4d 61 63 72 6f 20  y false.  Macro 
4bb0: 6c 69 6b 65 6c 79 28 29 20 73 75 72 72 6f 75 6e  likely() surroun
4bc0: 64 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20  ds.** a boolean 
4bd0: 65 78 70 72 65 73 73 69 6f 6e 20 74 68 61 74 20  expression that 
4be0: 69 73 20 75 73 75 61 6c 6c 79 20 74 72 75 65 2e  is usually true.
4bf0: 20 20 47 43 43 20 69 73 20 61 62 6c 65 20 74 6f    GCC is able to
4c00: 0a 2a 2a 20 75 73 65 20 74 68 65 73 65 20 68 69  .** use these hi
4c10: 6e 74 73 20 74 6f 20 67 65 6e 65 72 61 74 65 20  nts to generate 
4c20: 62 65 74 74 65 72 20 63 6f 64 65 2c 20 73 6f 6d  better code, som
4c30: 65 74 69 6d 65 73 2e 0a 2a 2f 0a 23 69 66 20 64  etimes..*/.#if d
4c40: 65 66 69 6e 65 64 28 5f 5f 47 4e 55 43 5f 5f 29  efined(__GNUC__)
4c50: 20 26 26 20 30 0a 23 20 64 65 66 69 6e 65 20 6c   && 0.# define l
4c60: 69 6b 65 6c 79 28 58 29 20 20 20 20 5f 5f 62 75  ikely(X)    __bu
4c70: 69 6c 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29  iltin_expect((X)
4c80: 2c 31 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c  ,1).# define unl
4c90: 69 6b 65 6c 79 28 58 29 20 20 5f 5f 62 75 69 6c  ikely(X)  __buil
4ca0: 74 69 6e 5f 65 78 70 65 63 74 28 28 58 29 2c 30  tin_expect((X),0
4cb0: 29 0a 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65  ).#else.# define
4cc0: 20 6c 69 6b 65 6c 79 28 58 29 20 20 20 20 21 21   likely(X)    !!
4cd0: 28 58 29 0a 23 20 64 65 66 69 6e 65 20 75 6e 6c  (X).# define unl
4ce0: 69 6b 65 6c 79 28 58 29 20 20 21 21 28 58 29 0a  ikely(X)  !!(X).
4cf0: 23 65 6e 64 69 66 0a 0a 2f 2a 2a 2a 2a 2a 2a 2a  #endif../*******
4d00: 2a 2a 2a 2a 2a 2a 2a 20 49 6e 63 6c 75 64 65 20  ******* Include 
4d10: 73 71 6c 69 74 65 33 2e 68 20 69 6e 20 74 68 65  sqlite3.h in the
4d20: 20 6d 69 64 64 6c 65 20 6f 66 20 73 71 6c 69 74   middle of sqlit
4d30: 65 49 6e 74 2e 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  eInt.h *********
4d40: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a  ******/./*******
4d50: 2a 2a 2a 2a 2a 2a 2a 20 42 65 67 69 6e 20 66 69  ******* Begin fi
4d60: 6c 65 20 73 71 6c 69 74 65 33 2e 68 20 2a 2a 2a  le sqlite3.h ***
4d70: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d80: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4d90: 2a 2a 2a 2a 2a 2a 2f 0a 2f 2a 0a 2a 2a 20 32 30  ******/./*.** 20
4da0: 30 31 20 53 65 70 74 65 6d 62 65 72 20 31 35 0a  01 September 15.
4db0: 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72  **.** The author
4dc0: 20 64 69 73 63 6c 61 69 6d 73 20 63 6f 70 79 72   disclaims copyr
4dd0: 69 67 68 74 20 74 6f 20 74 68 69 73 20 73 6f 75  ight to this sou
4de0: 72 63 65 20 63 6f 64 65 2e 20 20 49 6e 20 70 6c  rce code.  In pl
4df0: 61 63 65 20 6f 66 0a 2a 2a 20 61 20 6c 65 67 61  ace of.** a lega
4e00: 6c 20 6e 6f 74 69 63 65 2c 20 68 65 72 65 20 69  l notice, here i
4e10: 73 20 61 20 62 6c 65 73 73 69 6e 67 3a 0a 2a 2a  s a blessing:.**
4e20: 0a 2a 2a 20 20 20 20 4d 61 79 20 79 6f 75 20 64  .**    May you d
4e30: 6f 20 67 6f 6f 64 20 61 6e 64 20 6e 6f 74 20 65  o good and not e
4e40: 76 69 6c 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79  vil..**    May y
4e50: 6f 75 20 66 69 6e 64 20 66 6f 72 67 69 76 65 6e  ou find forgiven
4e60: 65 73 73 20 66 6f 72 20 79 6f 75 72 73 65 6c 66  ess for yourself
4e70: 20 61 6e 64 20 66 6f 72 67 69 76 65 20 6f 74 68   and forgive oth
4e80: 65 72 73 2e 0a 2a 2a 20 20 20 20 4d 61 79 20 79  ers..**    May y
4e90: 6f 75 20 73 68 61 72 65 20 66 72 65 65 6c 79 2c  ou share freely,
4ea0: 20 6e 65 76 65 72 20 74 61 6b 69 6e 67 20 6d 6f   never taking mo
4eb0: 72 65 20 74 68 61 6e 20 79 6f 75 20 67 69 76 65  re than you give
4ec0: 2e 0a 2a 2a 0a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..**.***********
4ed0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ee0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4ef0: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
4f00: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 0a 2a  **************.*
4f10: 2a 20 54 68 69 73 20 68 65 61 64 65 72 20 66 69  * This header fi
4f20: 6c 65 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  le defines the i
4f30: 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 74 68  nterface that th
4f40: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
4f50: 0a 2a 2a 20 70 72 65 73 65 6e 74 73 20 74 6f 20  .** presents to 
4f60: 63 6c 69 65 6e 74 20 70 72 6f 67 72 61 6d 73 2e  client programs.
4f70: 20 20 49 66 20 61 20 43 2d 66 75 6e 63 74 69 6f    If a C-functio
4f80: 6e 2c 20 73 74 72 75 63 74 75 72 65 2c 20 64 61  n, structure, da
4f90: 74 61 74 79 70 65 2c 0a 2a 2a 20 6f 72 20 63 6f  tatype,.** or co
4fa0: 6e 73 74 61 6e 74 20 64 65 66 69 6e 69 74 69 6f  nstant definitio
4fb0: 6e 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  n does not appea
4fc0: 72 20 69 6e 20 74 68 69 73 20 66 69 6c 65 2c 20  r in this file, 
4fd0: 74 68 65 6e 20 69 74 20 69 73 0a 2a 2a 20 6e 6f  then it is.** no
4fe0: 74 20 61 20 70 75 62 6c 69 73 68 65 64 20 41 50  t a published AP
4ff0: 49 20 6f 66 20 53 51 4c 69 74 65 2c 20 69 73 20  I of SQLite, is 
5000: 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61 6e 67  subject to chang
5010: 65 20 77 69 74 68 6f 75 74 0a 2a 2a 20 6e 6f 74  e without.** not
5020: 69 63 65 2c 20 61 6e 64 20 73 68 6f 75 6c 64 20  ice, and should 
5030: 6e 6f 74 20 62 65 20 72 65 66 65 72 65 6e 63 65  not be reference
5040: 64 20 62 79 20 70 72 6f 67 72 61 6d 73 20 74 68  d by programs th
5050: 61 74 20 75 73 65 20 53 51 4c 69 74 65 2e 0a 2a  at use SQLite..*
5060: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
5070: 20 64 65 66 69 6e 69 74 69 6f 6e 73 20 74 68 61   definitions tha
5080: 74 20 61 72 65 20 69 6e 20 74 68 69 73 20 66 69  t are in this fi
5090: 6c 65 20 61 72 65 20 6d 61 72 6b 65 64 20 61 73  le are marked as
50a0: 0a 2a 2a 20 22 65 78 70 65 72 69 6d 65 6e 74 61  .** "experimenta
50b0: 6c 22 2e 20 20 45 78 70 65 72 69 6d 65 6e 74 61  l".  Experimenta
50c0: 6c 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  l interfaces are
50d0: 20 6e 6f 72 6d 61 6c 6c 79 20 6e 65 77 0a 2a 2a   normally new.**
50e0: 20 66 65 61 74 75 72 65 73 20 72 65 63 65 6e 74   features recent
50f0: 6c 79 20 61 64 64 65 64 20 74 6f 20 53 51 4c 69  ly added to SQLi
5100: 74 65 2e 20 20 57 65 20 64 6f 20 6e 6f 74 20 61  te.  We do not a
5110: 6e 74 69 63 69 70 61 74 65 20 63 68 61 6e 67 65  nticipate change
5120: 73 0a 2a 2a 20 74 6f 20 65 78 70 65 72 69 6d 65  s.** to experime
5130: 6e 74 61 6c 20 69 6e 74 65 72 66 61 63 65 73 20  ntal interfaces 
5140: 62 75 74 20 72 65 73 65 72 76 65 20 74 68 65 20  but reserve the 
5150: 72 69 67 68 74 20 74 6f 20 6d 61 6b 65 20 6d 69  right to make mi
5160: 6e 6f 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69  nor changes.** i
5170: 66 20 65 78 70 65 72 69 65 6e 63 65 20 66 72 6f  f experience fro
5180: 6d 20 75 73 65 20 22 69 6e 20 74 68 65 20 77 69  m use "in the wi
5190: 6c 64 22 20 73 75 67 67 65 73 74 20 73 75 63 68  ld" suggest such
51a0: 20 63 68 61 6e 67 65 73 20 61 72 65 20 70 72 75   changes are pru
51b0: 64 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  dent..**.** The 
51c0: 6f 66 66 69 63 69 61 6c 20 43 2d 6c 61 6e 67 75  official C-langu
51d0: 61 67 65 20 41 50 49 20 64 6f 63 75 6d 65 6e 74  age API document
51e0: 61 74 69 6f 6e 20 66 6f 72 20 53 51 4c 69 74 65  ation for SQLite
51f0: 20 69 73 20 64 65 72 69 76 65 64 0a 2a 2a 20 66   is derived.** f
5200: 72 6f 6d 20 63 6f 6d 6d 65 6e 74 73 20 69 6e 20  rom comments in 
5210: 74 68 69 73 20 66 69 6c 65 2e 20 20 54 68 69 73  this file.  This
5220: 20 66 69 6c 65 20 69 73 20 74 68 65 20 61 75 74   file is the aut
5230: 68 6f 72 69 74 61 74 69 76 65 20 73 6f 75 72 63  horitative sourc
5240: 65 0a 2a 2a 20 6f 6e 20 68 6f 77 20 53 51 4c 69  e.** on how SQLi
5250: 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  te interfaces ar
5260: 65 20 73 75 70 70 6f 73 65 20 74 6f 20 6f 70 65  e suppose to ope
5270: 72 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rate..**.** The 
5280: 6e 61 6d 65 20 6f 66 20 74 68 69 73 20 66 69 6c  name of this fil
5290: 65 20 75 6e 64 65 72 20 63 6f 6e 66 69 67 75 72  e under configur
52a0: 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74  ation management
52b0: 20 69 73 20 22 73 71 6c 69 74 65 2e 68 2e 69 6e   is "sqlite.h.in
52c0: 22 2e 0a 2a 2a 20 54 68 65 20 6d 61 6b 65 66 69  "..** The makefi
52d0: 6c 65 20 6d 61 6b 65 73 20 73 6f 6d 65 20 6d 69  le makes some mi
52e0: 6e 6f 72 20 63 68 61 6e 67 65 73 20 74 6f 20 74  nor changes to t
52f0: 68 69 73 20 66 69 6c 65 20 28 73 75 63 68 20 61  his file (such a
5300: 73 20 69 6e 73 65 72 74 69 6e 67 0a 2a 2a 20 74  s inserting.** t
5310: 68 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  he version numbe
5320: 72 29 20 61 6e 64 20 63 68 61 6e 67 65 73 20 69  r) and changes i
5330: 74 73 20 6e 61 6d 65 20 74 6f 20 22 73 71 6c 69  ts name to "sqli
5340: 74 65 33 2e 68 22 20 61 73 0a 2a 2a 20 70 61 72  te3.h" as.** par
5350: 74 20 6f 66 20 74 68 65 20 62 75 69 6c 64 20 70  t of the build p
5360: 72 6f 63 65 73 73 2e 0a 2a 2f 0a 23 69 66 6e 64  rocess..*/.#ifnd
5370: 65 66 20 5f 53 51 4c 49 54 45 33 5f 48 5f 0a 23  ef _SQLITE3_H_.#
5380: 64 65 66 69 6e 65 20 5f 53 51 4c 49 54 45 33 5f  define _SQLITE3_
5390: 48 5f 0a 23 69 6e 63 6c 75 64 65 20 3c 73 74 64  H_.#include <std
53a0: 61 72 67 2e 68 3e 20 20 20 20 20 2f 2a 20 4e 65  arg.h>     /* Ne
53b0: 65 64 65 64 20 66 6f 72 20 74 68 65 20 64 65 66  eded for the def
53c0: 69 6e 69 74 69 6f 6e 20 6f 66 20 76 61 5f 6c 69  inition of va_li
53d0: 73 74 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b  st */../*.** Mak
53e0: 65 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61  e sure we can ca
53f0: 6c 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72  ll this stuff fr
5400: 6f 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 20 30  om C++..*/.#if 0
5410: 0a 65 78 74 65 72 6e 20 22 43 22 20 7b 0a 23 65  .extern "C" {.#e
5420: 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a 2a 20 41 64 64  ndif.../*.** Add
5430: 20 74 68 65 20 61 62 69 6c 69 74 79 20 74 6f 20   the ability to 
5440: 6f 76 65 72 72 69 64 65 20 27 65 78 74 65 72 6e  override 'extern
5450: 27 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c  '.*/.#ifndef SQL
5460: 49 54 45 5f 45 58 54 45 52 4e 0a 23 20 64 65 66  ITE_EXTERN.# def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 54 45 52  ine SQLITE_EXTER
5480: 4e 20 65 78 74 65 72 6e 0a 23 65 6e 64 69 66 0a  N extern.#endif.
5490: 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
54a0: 41 50 49 0a 23 20 64 65 66 69 6e 65 20 53 51 4c  API.# define SQL
54b0: 49 54 45 5f 41 50 49 0a 23 65 6e 64 69 66 0a 0a  ITE_API.#endif..
54c0: 0a 2f 2a 0a 2a 2a 20 54 68 65 73 65 20 6e 6f 2d  ./*.** These no-
54d0: 6f 70 20 6d 61 63 72 6f 73 20 61 72 65 20 75 73  op macros are us
54e0: 65 64 20 69 6e 20 66 72 6f 6e 74 20 6f 66 20 69  ed in front of i
54f0: 6e 74 65 72 66 61 63 65 73 20 74 6f 20 6d 61 72  nterfaces to mar
5500: 6b 20 74 68 6f 73 65 0a 2a 2a 20 69 6e 74 65 72  k those.** inter
5510: 66 61 63 65 73 20 61 73 20 65 69 74 68 65 72 20  faces as either 
5520: 64 65 70 72 65 63 61 74 65 64 20 6f 72 20 65 78  deprecated or ex
5530: 70 65 72 69 6d 65 6e 74 61 6c 2e 20 20 4e 65 77  perimental.  New
5540: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
5550: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 75 73 65 20   should not use 
5560: 64 65 70 72 65 63 61 74 65 64 20 69 6e 74 65 72  deprecated inter
5570: 66 61 63 65 73 20 2d 20 74 68 65 79 20 61 72 65  faces - they are
5580: 20 73 75 70 70 6f 72 74 20 66 6f 72 20 62 61 63   support for bac
5590: 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74  kwards.** compat
55a0: 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 20 20 41  ibility only.  A
55b0: 70 70 6c 69 63 61 74 69 6f 6e 20 77 72 69 74 65  pplication write
55c0: 72 73 20 73 68 6f 75 6c 64 20 62 65 20 61 77 61  rs should be awa
55d0: 72 65 20 74 68 61 74 0a 2a 2a 20 65 78 70 65 72  re that.** exper
55e0: 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66 61 63  imental interfac
55f0: 65 73 20 61 72 65 20 73 75 62 6a 65 63 74 20 74  es are subject t
5600: 6f 20 63 68 61 6e 67 65 20 69 6e 20 70 6f 69 6e  o change in poin
5610: 74 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2a 0a 2a  t releases..**.*
5620: 2a 20 54 68 65 73 65 20 6d 61 63 72 6f 73 20 75  * These macros u
5630: 73 65 64 20 74 6f 20 72 65 73 6f 6c 76 65 20 74  sed to resolve t
5640: 6f 20 76 61 72 69 6f 75 73 20 6b 69 6e 64 73 20  o various kinds 
5650: 6f 66 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69  of compiler magi
5660: 63 20 74 68 61 74 0a 2a 2a 20 77 6f 75 6c 64 20  c that.** would 
5670: 67 65 6e 65 72 61 74 65 20 77 61 72 6e 69 6e 67  generate warning
5680: 20 6d 65 73 73 61 67 65 73 20 77 68 65 6e 20 74   messages when t
5690: 68 65 79 20 77 65 72 65 20 75 73 65 64 2e 20 20  hey were used.  
56a0: 42 75 74 20 74 68 61 74 0a 2a 2a 20 63 6f 6d 70  But that.** comp
56b0: 69 6c 65 72 20 6d 61 67 69 63 20 65 6e 64 65 64  iler magic ended
56c0: 20 75 70 20 67 65 6e 65 72 61 74 69 6e 67 20 73   up generating s
56d0: 75 63 68 20 61 20 66 6c 75 72 72 79 20 6f 66 20  uch a flurry of 
56e0: 62 75 67 20 72 65 70 6f 72 74 73 0a 2a 2a 20 74  bug reports.** t
56f0: 68 61 74 20 77 65 20 68 61 76 65 20 74 61 6b 65  hat we have take
5700: 6e 20 69 74 20 61 6c 6c 20 6f 75 74 20 61 6e 64  n it all out and
5710: 20 67 6f 6e 65 20 62 61 63 6b 20 74 6f 20 75 73   gone back to us
5720: 69 6e 67 20 73 69 6d 70 6c 65 0a 2a 2a 20 6e 6f  ing simple.** no
5730: 6f 70 20 6d 61 63 72 6f 73 2e 0a 2a 2f 0a 23 64  op macros..*/.#d
5740: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 50  efine SQLITE_DEP
5750: 52 45 43 41 54 45 44 0a 23 64 65 66 69 6e 65 20  RECATED.#define 
5760: 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
5770: 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20 45 6e 73 75 72  TAL../*.** Ensur
5780: 65 20 74 68 65 73 65 20 73 79 6d 62 6f 6c 73 20  e these symbols 
5790: 77 65 72 65 20 6e 6f 74 20 64 65 66 69 6e 65 64  were not defined
57a0: 20 62 79 20 73 6f 6d 65 20 70 72 65 76 69 6f 75   by some previou
57b0: 73 20 68 65 61 64 65 72 20 66 69 6c 65 2e 0a 2a  s header file..*
57c0: 2f 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f  /.#ifdef SQLITE_
57d0: 56 45 52 53 49 4f 4e 0a 23 20 75 6e 64 65 66 20  VERSION.# undef 
57e0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23  SQLITE_VERSION.#
57f0: 65 6e 64 69 66 0a 23 69 66 64 65 66 20 53 51 4c  endif.#ifdef SQL
5800: 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42  ITE_VERSION_NUMB
5810: 45 52 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54  ER.# undef SQLIT
5820: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
5830: 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
5840: 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65  API3REF: Compile
5850: 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 56 65  -Time Library Ve
5860: 72 73 69 6f 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a  rsion Numbers.**
5870: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
5880: 45 5f 56 45 52 53 49 4f 4e 5d 20 43 20 70 72 65  E_VERSION] C pre
5890: 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20  processor macro 
58a0: 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 2e 68  in the sqlite3.h
58b0: 20 68 65 61 64 65 72 0a 2a 2a 20 65 76 61 6c 75   header.** evalu
58c0: 61 74 65 73 20 74 6f 20 61 20 73 74 72 69 6e 67  ates to a string
58d0: 20 6c 69 74 65 72 61 6c 20 74 68 61 74 20 69 73   literal that is
58e0: 20 74 68 65 20 53 51 4c 69 74 65 20 76 65 72 73   the SQLite vers
58f0: 69 6f 6e 20 69 6e 20 74 68 65 0a 2a 2a 20 66 6f  ion in the.** fo
5900: 72 6d 61 74 20 22 58 2e 59 2e 5a 22 20 77 68 65  rmat "X.Y.Z" whe
5910: 72 65 20 58 20 69 73 20 74 68 65 20 6d 61 6a 6f  re X is the majo
5920: 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  r version number
5930: 20 28 61 6c 77 61 79 73 20 33 20 66 6f 72 0a 2a   (always 3 for.*
5940: 2a 20 53 51 4c 69 74 65 33 29 20 61 6e 64 20 59  * SQLite3) and Y
5950: 20 69 73 20 74 68 65 20 6d 69 6e 6f 72 20 76 65   is the minor ve
5960: 72 73 69 6f 6e 20 6e 75 6d 62 65 72 20 61 6e 64  rsion number and
5970: 20 5a 20 69 73 20 74 68 65 20 72 65 6c 65 61 73   Z is the releas
5980: 65 20 6e 75 6d 62 65 72 2e 29 5e 0a 2a 2a 20 5e  e number.)^.** ^
5990: 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52  (The [SQLITE_VER
59a0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 20 43 20 70  SION_NUMBER] C p
59b0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
59c0: 6f 20 72 65 73 6f 6c 76 65 73 20 74 6f 20 61 6e  o resolves to an
59d0: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 77 69 74 68   integer.** with
59e0: 20 74 68 65 20 76 61 6c 75 65 20 28 58 2a 31 30   the value (X*10
59f0: 30 30 30 30 30 20 2b 20 59 2a 31 30 30 30 20 2b  00000 + Y*1000 +
5a00: 20 5a 29 20 77 68 65 72 65 20 58 2c 20 59 2c 20   Z) where X, Y, 
5a10: 61 6e 64 20 5a 20 61 72 65 20 74 68 65 20 73 61  and Z are the sa
5a20: 6d 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 75 73  me.** numbers us
5a30: 65 64 20 69 6e 20 5b 53 51 4c 49 54 45 5f 56 45  ed in [SQLITE_VE
5a40: 52 53 49 4f 4e 5d 2e 29 5e 0a 2a 2a 20 54 68 65  RSION].)^.** The
5a50: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
5a60: 4e 55 4d 42 45 52 20 66 6f 72 20 61 6e 79 20 67  NUMBER for any g
5a70: 69 76 65 6e 20 72 65 6c 65 61 73 65 20 6f 66 20  iven release of 
5a80: 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f  SQLite will also
5a90: 0a 2a 2a 20 62 65 20 6c 61 72 67 65 72 20 74 68  .** be larger th
5aa0: 61 6e 20 74 68 65 20 72 65 6c 65 61 73 65 20 66  an the release f
5ab0: 72 6f 6d 20 77 68 69 63 68 20 69 74 20 69 73 20  rom which it is 
5ac0: 64 65 72 69 76 65 64 2e 20 20 45 69 74 68 65 72  derived.  Either
5ad0: 20 59 20 77 69 6c 6c 0a 2a 2a 20 62 65 20 68 65   Y will.** be he
5ae0: 6c 64 20 63 6f 6e 73 74 61 6e 74 20 61 6e 64 20  ld constant and 
5af0: 5a 20 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d  Z will be increm
5b00: 65 6e 74 65 64 20 6f 72 20 65 6c 73 65 20 59 20  ented or else Y 
5b10: 77 69 6c 6c 20 62 65 20 69 6e 63 72 65 6d 65 6e  will be incremen
5b20: 74 65 64 0a 2a 2a 20 61 6e 64 20 5a 20 77 69 6c  ted.** and Z wil
5b30: 6c 20 62 65 20 72 65 73 65 74 20 74 6f 20 7a 65  l be reset to ze
5b40: 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 69 6e 63 65 20  ro..**.** Since 
5b50: 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31 38 2c 20  version 3.6.18, 
5b60: 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 63 6f  SQLite source co
5b70: 64 65 20 68 61 73 20 62 65 65 6e 20 73 74 6f 72  de has been stor
5b80: 65 64 20 69 6e 20 74 68 65 0a 2a 2a 20 3c 61 20  ed in the.** <a 
5b90: 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77  href="http://www
5ba0: 2e 66 6f 73 73 69 6c 2d 73 63 6d 2e 6f 72 67 2f  .fossil-scm.org/
5bb0: 22 3e 46 6f 73 73 69 6c 20 63 6f 6e 66 69 67 75  ">Fossil configu
5bc0: 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e  ration managemen
5bd0: 74 0a 2a 2a 20 73 79 73 74 65 6d 3c 2f 61 3e 2e  t.** system</a>.
5be0: 20 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 53 4f    ^The SQLITE_SO
5bf0: 55 52 43 45 5f 49 44 20 6d 61 63 72 6f 20 65 76  URCE_ID macro ev
5c00: 61 6c 75 61 74 65 73 20 74 6f 0a 2a 2a 20 61 20  aluates to.** a 
5c10: 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 64 65  string which ide
5c20: 6e 74 69 66 69 65 73 20 61 20 70 61 72 74 69 63  ntifies a partic
5c30: 75 6c 61 72 20 63 68 65 63 6b 2d 69 6e 20 6f 66  ular check-in of
5c40: 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 74 68 69   SQLite.** withi
5c50: 6e 20 69 74 73 20 63 6f 6e 66 69 67 75 72 61 74  n its configurat
5c60: 69 6f 6e 20 6d 61 6e 61 67 65 6d 65 6e 74 20 73  ion management s
5c70: 79 73 74 65 6d 2e 20 20 5e 54 68 65 20 53 51 4c  ystem.  ^The SQL
5c80: 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 0a 2a 2a  ITE_SOURCE_ID.**
5c90: 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e 73   string contains
5ca0: 20 74 68 65 20 64 61 74 65 20 61 6e 64 20 74 69   the date and ti
5cb0: 6d 65 20 6f 66 20 74 68 65 20 63 68 65 63 6b 2d  me of the check-
5cc0: 69 6e 20 28 55 54 43 29 20 61 6e 64 20 61 6e 20  in (UTC) and an 
5cd0: 53 48 41 31 0a 2a 2a 20 68 61 73 68 20 6f 66 20  SHA1.** hash of 
5ce0: 74 68 65 20 65 6e 74 69 72 65 20 73 6f 75 72 63  the entire sourc
5cf0: 65 20 74 72 65 65 2e 0a 2a 2a 0a 2a 2a 20 53 65  e tree..**.** Se
5d00: 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
5d10: 5f 6c 69 62 76 65 72 73 69 6f 6e 28 29 5d 2c 0a  _libversion()],.
5d20: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 62 76  ** [sqlite3_libv
5d30: 65 72 73 69 6f 6e 5f 6e 75 6d 62 65 72 28 29 5d  ersion_number()]
5d40: 2c 20 5b 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  , [sqlite3_sourc
5d50: 65 69 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  eid()],.** [sqli
5d60: 74 65 5f 76 65 72 73 69 6f 6e 28 29 5d 20 61 6e  te_version()] an
5d70: 64 20 5b 73 71 6c 69 74 65 5f 73 6f 75 72 63 65  d [sqlite_source
5d80: 5f 69 64 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69  _id()]..*/.#defi
5d90: 6e 65 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  ne SQLITE_VERSIO
5da0: 4e 20 20 20 20 20 20 20 20 22 33 2e 37 2e 31 36  N        "3.7.16
5db0: 22 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ".#define SQLITE
5dc0: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20  _VERSION_NUMBER 
5dd0: 33 30 30 37 30 31 36 0a 23 64 65 66 69 6e 65 20  3007016.#define 
5de0: 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44  SQLITE_SOURCE_ID
5df0: 20 20 20 20 20 20 22 32 30 31 33 2d 30 33 2d 31        "2013-03-1
5e00: 33 20 30 30 3a 31 33 3a 32 35 20 38 33 39 61 61  3 00:13:25 839aa
5e10: 39 31 66 61 66 31 64 62 37 30 32 35 64 39 30 66  91faf1db7025d90f
5e20: 61 33 63 36 35 65 35 30 65 66 62 38 32 39 62 30  a3c65e50efb829b0
5e30: 35 33 62 22 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  53b"../*.** CAPI
5e40: 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
5e50: 69 62 72 61 72 79 20 56 65 72 73 69 6f 6e 20 4e  ibrary Version N
5e60: 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59 57 4f 52  umbers.** KEYWOR
5e70: 44 53 3a 20 73 71 6c 69 74 65 33 5f 76 65 72 73  DS: sqlite3_vers
5e80: 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 73 6f 75  ion, sqlite3_sou
5e90: 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73  rceid.**.** Thes
5ea0: 65 20 69 6e 74 65 72 66 61 63 65 73 20 70 72 6f  e interfaces pro
5eb0: 76 69 64 65 20 74 68 65 20 73 61 6d 65 20 69 6e  vide the same in
5ec0: 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20 74 68 65  formation as the
5ed0: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
5ee0: 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45  ],.** [SQLITE_VE
5ef0: 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2c 20 61  RSION_NUMBER], a
5f00: 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f 55 52 43  nd [SQLITE_SOURC
5f10: 45 5f 49 44 5d 20 43 20 70 72 65 70 72 6f 63 65  E_ID] C preproce
5f20: 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a 2a 20 62  ssor macros.** b
5f30: 75 74 20 61 72 65 20 61 73 73 6f 63 69 61 74 65  ut are associate
5f40: 64 20 77 69 74 68 20 74 68 65 20 6c 69 62 72 61  d with the libra
5f50: 72 79 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68  ry instead of th
5f60: 65 20 68 65 61 64 65 72 20 66 69 6c 65 2e 20 20  e header file.  
5f70: 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a 20 70 72  ^(Cautious.** pr
5f80: 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74 20  ogrammers might 
5f90: 69 6e 63 6c 75 64 65 20 61 73 73 65 72 74 28 29  include assert()
5fa0: 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74   statements in t
5fb0: 68 65 69 72 20 61 70 70 6c 69 63 61 74 69 6f 6e  heir application
5fc0: 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79 20 74 68   to.** verify th
5fd0: 61 74 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  at values return
5fe0: 65 64 20 62 79 20 74 68 65 73 65 20 69 6e 74 65  ed by these inte
5ff0: 72 66 61 63 65 73 20 6d 61 74 63 68 20 74 68 65  rfaces match the
6000: 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a 20 74 68   macros in.** th
6010: 65 20 68 65 61 64 65 72 2c 20 61 6e 64 20 74 68  e header, and th
6020: 75 73 20 69 6e 73 75 72 65 20 74 68 61 74 20 74  us insure that t
6030: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
6040: 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69  s.** compiled wi
6050: 74 68 20 6d 61 74 63 68 69 6e 67 20 6c 69 62 72  th matching libr
6060: 61 72 79 20 61 6e 64 20 68 65 61 64 65 72 20 66  ary and header f
6070: 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  iles..**.** <blo
6080: 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
6090: 20 61 73 73 65 72 74 28 20 73 71 6c 69 74 65 33   assert( sqlite3
60a0: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
60b0: 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f 56 45 52  er()==SQLITE_VER
60c0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29 3b 0a 2a  SION_NUMBER );.*
60d0: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
60e0: 28 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69  (sqlite3_sourcei
60f0: 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f 55 52 43  d(),SQLITE_SOURC
6100: 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a 2a 20 61  E_ID)==0 );.** a
6110: 73 73 65 72 74 28 20 73 74 72 63 6d 70 28 73 71  ssert( strcmp(sq
6120: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
6130: 28 29 2c 53 51 4c 49 54 45 5f 56 45 52 53 49 4f  (),SQLITE_VERSIO
6140: 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c 2f 70 72  N)==0 );.** </pr
6150: 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
6160: 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
6170: 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d 20 73  ite3_version[] s
6180: 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e 74 20 63  tring constant c
6190: 6f 6e 74 61 69 6e 73 20 74 68 65 20 74 65 78 74  ontains the text
61a0: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56 45 52 53   of [SQLITE_VERS
61b0: 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f 2e 20 20  ION].** macro.  
61c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c 69 62  ^The sqlite3_lib
61d0: 76 65 72 73 69 6f 6e 28 29 20 66 75 6e 63 74 69  version() functi
61e0: 6f 6e 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  on returns a poi
61f0: 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 74  nter to the.** t
6200: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 65  o the sqlite3_ve
6210: 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e 67 20 63  rsion[] string c
6220: 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65 20 73 71  onstant.  The sq
6230: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
6240: 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69  ().** function i
6250: 73 20 70 72 6f 76 69 64 65 64 20 66 6f 72 20 75  s provided for u
6260: 73 65 20 69 6e 20 44 4c 4c 73 20 73 69 6e 63 65  se in DLLs since
6270: 20 44 4c 4c 20 75 73 65 72 73 20 75 73 75 61 6c   DLL users usual
6280: 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76 65 0a 2a  ly do not have.*
6290: 2a 20 64 69 72 65 63 74 20 61 63 63 65 73 73 20  * direct access 
62a0: 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61  to string consta
62b0: 6e 74 73 20 77 69 74 68 69 6e 20 74 68 65 20 44  nts within the D
62c0: 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  LL.  ^The.** sql
62d0: 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f  ite3_libversion_
62e0: 6e 75 6d 62 65 72 28 29 20 66 75 6e 63 74 69 6f  number() functio
62f0: 6e 20 72 65 74 75 72 6e 73 20 61 6e 20 69 6e 74  n returns an int
6300: 65 67 65 72 20 65 71 75 61 6c 20 74 6f 0a 2a 2a  eger equal to.**
6310: 20 5b 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e   [SQLITE_VERSION
6320: 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54 68 65 20  _NUMBER].  ^The 
6330: 73 71 6c 69 74 65 33 5f 73 6f 75 72 63 65 69 64  sqlite3_sourceid
6340: 28 29 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  () function retu
6350: 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  rns .** a pointe
6360: 72 20 74 6f 20 61 20 73 74 72 69 6e 67 20 63 6f  r to a string co
6370: 6e 73 74 61 6e 74 20 77 68 6f 73 65 20 76 61 6c  nstant whose val
6380: 75 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 61  ue is the same a
6390: 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  s the .** [SQLIT
63a0: 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20 43 20 70  E_SOURCE_ID] C p
63b0: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
63c0: 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  o..**.** See als
63d0: 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65 72 73 69  o: [sqlite_versi
63e0: 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
63f0: 65 5f 73 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a  e_source_id()]..
6400: 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
6410: 6e 73 74 20 63 68 61 72 20 73 71 6c 69 74 65 33  nst char sqlite3
6420: 5f 76 65 72 73 69 6f 6e 5b 5d 20 3d 20 53 51 4c  _version[] = SQL
6430: 49 54 45 5f 56 45 52 53 49 4f 4e 3b 0a 53 51 4c  ITE_VERSION;.SQL
6440: 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63 68  ITE_API const ch
6450: 61 72 20 2a 73 71 6c 69 74 65 33 5f 6c 69 62 76  ar *sqlite3_libv
6460: 65 72 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 53 51  ersion(void);.SQ
6470: 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 63  LITE_API const c
6480: 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75  har *sqlite3_sou
6490: 72 63 65 69 64 28 76 6f 69 64 29 3b 0a 53 51 4c  rceid(void);.SQL
64a0: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
64b0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
64c0: 75 6d 62 65 72 28 76 6f 69 64 29 3b 0a 0a 2f 2a  umber(void);../*
64d0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
64e0: 6e 2d 54 69 6d 65 20 4c 69 62 72 61 72 79 20 43  n-Time Library C
64f0: 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f 70 74 69 6f  ompilation Optio
6500: 6e 73 20 44 69 61 67 6e 6f 73 74 69 63 73 0a 2a  ns Diagnostics.*
6510: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
6520: 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  3_compileoption_
6530: 75 73 65 64 28 29 20 66 75 6e 63 74 69 6f 6e 20  used() function 
6540: 72 65 74 75 72 6e 73 20 30 20 6f 72 20 31 20 0a  returns 0 or 1 .
6550: 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20 77 68  ** indicating wh
6560: 65 74 68 65 72 20 74 68 65 20 73 70 65 63 69 66  ether the specif
6570: 69 65 64 20 6f 70 74 69 6f 6e 20 77 61 73 20 64  ied option was d
6580: 65 66 69 6e 65 64 20 61 74 20 0a 2a 2a 20 63 6f  efined at .** co
6590: 6d 70 69 6c 65 20 74 69 6d 65 2e 20 20 5e 54 68  mpile time.  ^Th
65a0: 65 20 53 51 4c 49 54 45 5f 20 70 72 65 66 69 78  e SQLITE_ prefix
65b0: 20 6d 61 79 20 62 65 20 6f 6d 69 74 74 65 64 20   may be omitted 
65c0: 66 72 6f 6d 20 74 68 65 20 0a 2a 2a 20 6f 70 74  from the .** opt
65d0: 69 6f 6e 20 6e 61 6d 65 20 70 61 73 73 65 64 20  ion name passed 
65e0: 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69  to sqlite3_compi
65f0: 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 2e  leoption_used().
6600: 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71    .**.** ^The sq
6610: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
6620: 69 6f 6e 5f 67 65 74 28 29 20 66 75 6e 63 74 69  ion_get() functi
6630: 6f 6e 20 61 6c 6c 6f 77 73 20 69 74 65 72 61 74  on allows iterat
6640: 69 6e 67 0a 2a 2a 20 6f 76 65 72 20 74 68 65 20  ing.** over the 
6650: 6c 69 73 74 20 6f 66 20 6f 70 74 69 6f 6e 73 20  list of options 
6660: 74 68 61 74 20 77 65 72 65 20 64 65 66 69 6e 65  that were define
6670: 64 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  d at compile tim
6680: 65 20 62 79 0a 2a 2a 20 72 65 74 75 72 6e 69 6e  e by.** returnin
6690: 67 20 74 68 65 20 4e 2d 74 68 20 63 6f 6d 70 69  g the N-th compi
66a0: 6c 65 20 74 69 6d 65 20 6f 70 74 69 6f 6e 20 73  le time option s
66b0: 74 72 69 6e 67 2e 20 20 5e 49 66 20 4e 20 69 73  tring.  ^If N is
66c0: 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 0a 2a   out of range,.*
66d0: 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  * sqlite3_compil
66e0: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 72 65  eoption_get() re
66f0: 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
6700: 6e 74 65 72 2e 20 20 5e 54 68 65 20 53 51 4c 49  nter.  ^The SQLI
6710: 54 45 5f 20 0a 2a 2a 20 70 72 65 66 69 78 20 69  TE_ .** prefix i
6720: 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 61  s omitted from a
6730: 6e 79 20 73 74 72 69 6e 67 73 20 72 65 74 75 72  ny strings retur
6740: 6e 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ned by .** sqlit
6750: 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e  e3_compileoption
6760: 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 53  _get()..**.** ^S
6770: 75 70 70 6f 72 74 20 66 6f 72 20 74 68 65 20 64  upport for the d
6780: 69 61 67 6e 6f 73 74 69 63 20 66 75 6e 63 74 69  iagnostic functi
6790: 6f 6e 73 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  ons sqlite3_comp
67a0: 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29  ileoption_used()
67b0: 0a 2a 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  .** and sqlite3_
67c0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
67d0: 74 28 29 20 6d 61 79 20 62 65 20 6f 6d 69 74 74  t() may be omitt
67e0: 65 64 20 62 79 20 73 70 65 63 69 66 79 69 6e 67  ed by specifying
67f0: 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
6800: 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c 45 4f 50 54  _OMIT_COMPILEOPT
6810: 49 4f 4e 5f 44 49 41 47 53 5d 20 6f 70 74 69 6f  ION_DIAGS] optio
6820: 6e 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  n at compile tim
6830: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
6840: 6f 3a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  o: SQL functions
6850: 20 5b 73 71 6c 69 74 65 5f 63 6f 6d 70 69 6c 65   [sqlite_compile
6860: 6f 70 74 69 6f 6e 5f 75 73 65 64 28 29 5d 20 61  option_used()] a
6870: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 5f 63 6f  nd.** [sqlite_co
6880: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
6890: 29 5d 20 61 6e 64 20 74 68 65 20 5b 63 6f 6d 70  )] and the [comp
68a0: 69 6c 65 5f 6f 70 74 69 6f 6e 73 20 70 72 61 67  ile_options prag
68b0: 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e 64 65 66 20  ma]..*/.#ifndef 
68c0: 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50  SQLITE_OMIT_COMP
68d0: 49 4c 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 0a  ILEOPTION_DIAGS.
68e0: 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
68f0: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
6900: 74 69 6f 6e 5f 75 73 65 64 28 63 6f 6e 73 74 20  tion_used(const 
6910: 63 68 61 72 20 2a 7a 4f 70 74 4e 61 6d 65 29 3b  char *zOptName);
6920: 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
6930: 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
6940: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65  compileoption_ge
6950: 74 28 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66  t(int N);.#endif
6960: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
6970: 3a 20 54 65 73 74 20 54 6f 20 53 65 65 20 49 66  : Test To See If
6980: 20 54 68 65 20 4c 69 62 72 61 72 79 20 49 73 20   The Library Is 
6990: 54 68 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a  Threadsafe.**.**
69a0: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68   ^The sqlite3_th
69b0: 72 65 61 64 73 61 66 65 28 29 20 66 75 6e 63 74  readsafe() funct
69c0: 69 6f 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f  ion returns zero
69d0: 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a   if and only if.
69e0: 2a 2a 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f  ** SQLite was co
69f0: 6d 70 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65  mpiled with mute
6a00: 78 69 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65  xing code omitte
6a10: 64 20 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20  d due to the.** 
6a20: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
6a30: 46 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  FE] compile-time
6a40: 20 6f 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65   option being se
6a50: 74 20 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51  t to 0..**.** SQ
6a60: 4c 69 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70  Lite can be comp
6a70: 69 6c 65 64 20 77 69 74 68 20 6f 72 20 77 69 74  iled with or wit
6a80: 68 6f 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57  hout mutexes.  W
6a90: 68 65 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49  hen.** the [SQLI
6aa0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43  TE_THREADSAFE] C
6ab0: 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
6ac0: 63 72 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d  cro is 1 or 2, m
6ad0: 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e  utexes.** are en
6ae0: 61 62 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65  abled and SQLite
6af0: 20 69 73 20 74 68 72 65 61 64 73 61 66 65 2e 20   is threadsafe. 
6b00: 20 57 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51   When the.** [SQ
6b10: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d  LITE_THREADSAFE]
6b20: 20 6d 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a   macro is 0, .**
6b30: 20 74 68 65 20 6d 75 74 65 78 65 73 20 61 72 65   the mutexes are
6b40: 20 6f 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f   omitted.  Witho
6b50: 75 74 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20  ut the mutexes, 
6b60: 69 74 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a  it is not safe.*
6b70: 2a 20 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20  * to use SQLite 
6b80: 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f  concurrently fro
6b90: 6d 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  m more than one 
6ba0: 74 68 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e  thread..**.** En
6bb0: 61 62 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69  abling mutexes i
6bc0: 6e 63 75 72 73 20 61 20 6d 65 61 73 75 72 61 62  ncurs a measurab
6bd0: 6c 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  le performance p
6be0: 65 6e 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66  enalty..** So if
6bf0: 20 73 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d   speed is of utm
6c00: 6f 73 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20  ost importance, 
6c10: 69 74 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74  it makes sense t
6c20: 6f 20 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65  o disable.** the
6c30: 20 6d 75 74 65 78 65 73 2e 20 20 42 75 74 20 66   mutexes.  But f
6c40: 6f 72 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74  or maximum safet
6c50: 79 2c 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c  y, mutexes shoul
6c60: 64 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  d be enabled..**
6c70: 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 65   ^The default be
6c80: 68 61 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75  havior is for mu
6c90: 74 65 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62  texes to be enab
6ca0: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  led..**.** This 
6cb0: 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
6cc0: 20 75 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c   used by an appl
6cd0: 69 63 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20  ication to make 
6ce0: 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
6cf0: 20 76 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69   version of SQLi
6d00: 74 65 20 74 68 61 74 20 69 74 20 69 73 20 6c 69  te that it is li
6d10: 6e 6b 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61  nking against wa
6d20: 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
6d30: 2a 2a 20 74 68 65 20 64 65 73 69 72 65 64 20 73  ** the desired s
6d40: 65 74 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53  etting of the [S
6d50: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
6d60: 5d 20 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54  ] macro..**.** T
6d70: 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e  his interface on
6d80: 6c 79 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68  ly reports on th
6d90: 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
6da0: 75 74 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20  utex setting.** 
6db0: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
6dc0: 48 52 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e  HREADSAFE] flag.
6dd0: 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
6de0: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
6df0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
6e00: 45 3d 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d  E=1 or =2 then m
6e10: 75 74 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c  utexes are enabl
6e20: 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 62 75  ed by default bu
6e30: 74 0a 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c  t.** can be full
6e40: 79 20 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64  y or partially d
6e50: 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
6e60: 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
6e70: 5f 63 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69  _config()].** wi
6e80: 74 68 20 74 68 65 20 76 65 72 62 73 20 5b 53 51  th the verbs [SQ
6e90: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
6ea0: 4c 45 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49  LETHREAD], [SQLI
6eb0: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
6ec0: 48 52 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53  HREAD],.** or [S
6ed0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
6ee0: 45 58 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75  EX].  ^(The retu
6ef0: 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a  rn value of the.
6f00: 2a 2a 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  ** sqlite3_threa
6f10: 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e  dsafe() function
6f20: 20 73 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20   shows only the 
6f30: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74  compile-time set
6f40: 74 69 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61  ting of.** threa
6f50: 64 20 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e  d safety, not an
6f60: 79 20 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67  y run-time chang
6f70: 65 73 20 74 6f 20 74 68 61 74 20 73 65 74 74 69  es to that setti
6f80: 6e 67 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71  ng made by.** sq
6f90: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20  lite3_config(). 
6fa0: 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20  In other words, 
6fb0: 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
6fc0: 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68   from sqlite3_th
6fd0: 72 65 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73  readsafe().** is
6fe0: 20 75 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61   unchanged by ca
6ff0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
7000: 6f 6e 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a  onfig().)^.**.**
7010: 20 53 65 65 20 74 68 65 20 5b 74 68 72 65 61 64   See the [thread
7020: 69 6e 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65  ing mode] docume
7030: 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69  ntation for addi
7040: 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
7050: 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  on..*/.SQLITE_AP
7060: 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68  I int sqlite3_th
7070: 72 65 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a  readsafe(void);.
7080: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
7090: 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
70a0: 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b  tion Handle.** K
70b0: 45 59 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61  EYWORDS: {databa
70c0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b  se connection} {
70d0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
70e0: 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68  ions}.**.** Each
70f0: 20 6f 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74   open SQLite dat
7100: 61 62 61 73 65 20 69 73 20 72 65 70 72 65 73 65  abase is represe
7110: 6e 74 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65  nted by a pointe
7120: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
7130: 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75   of.** the opaqu
7140: 65 20 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65  e structure name
7150: 64 20 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74  d "sqlite3".  It
7160: 20 69 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68   is useful to th
7170: 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65  ink of an sqlite
7180: 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20  3.** pointer as 
7190: 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20  an object.  The 
71a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
71b0: 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
71c0: 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  6()], and.** [sq
71d0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
71e0: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
71f0: 69 74 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73  its constructors
7200: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  , and [sqlite3_c
7210: 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  lose()].** and [
7220: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
7230: 28 29 5d 20 61 72 65 20 69 74 73 20 64 65 73 74  ()] are its dest
7240: 72 75 63 74 6f 72 73 2e 20 20 54 68 65 72 65 20  ructors.  There 
7250: 61 72 65 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a  are many other.*
7260: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  * interfaces (su
7270: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
7280: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
7290: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
72a0: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
72b0: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
72c0: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
72d0: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
72e0: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
72f0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
7300: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
7310: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7320: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
7330: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
7340: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
7350: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
7360: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
7370: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
7380: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
7390: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
73a0: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
73b0: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
73c0: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
73d0: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
73e0: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
73f0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
7400: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
7410: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
7420: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
7430: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
7440: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
7450: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
7460: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
7470: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
7480: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
7490: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
74a0: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
74b0: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
74c0: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
74d0: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
74e0: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
74f0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
7500: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
7510: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
7520: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
7530: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
7540: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
7550: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
7560: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
7570: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
7580: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
7590: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
75a0: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
75b0: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
75c0: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
75d0: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
75e0: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
75f0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
7600: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
7610: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
7620: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
7630: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
7640: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
7650: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
7660: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
7670: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
7680: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
7690: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
76a0: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
76b0: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
76c0: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
76d0: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
76e0: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
76f0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
7700: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
7710: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
7720: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
7730: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
7740: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
7750: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
7760: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
7770: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
7780: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
7790: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
77a0: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
77b0: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
77c0: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
77d0: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
77e0: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
77f0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
7800: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
7810: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
7820: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
7830: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
7840: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
7850: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
7860: 74 65 33 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20  te3_close() and 
7870: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
7880: 28 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  () routines are 
7890: 64 65 73 74 72 75 63 74 6f 72 73 0a 2a 2a 20 66  destructors.** f
78a0: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d  or the [sqlite3]
78b0: 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c   object..** ^Cal
78c0: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6c  ls to sqlite3_cl
78d0: 6f 73 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ose() and sqlite
78e0: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 72 65 74  3_close_v2() ret
78f0: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
7900: 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
7910: 5d 20 6f 62 6a 65 63 74 20 69 73 20 73 75 63 63  ] object is succ
7920: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
7930: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
7940: 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f 75 72 63  iated.** resourc
7950: 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63 61 74  es are deallocat
7960: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
7970: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
7980: 63 74 69 6f 6e 20 69 73 20 61 73 73 6f 63 69 61  ction is associa
7990: 74 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  ted with unfinal
79a0: 69 7a 65 64 20 70 72 65 70 61 72 65 64 0a 2a 2a  ized prepared.**
79b0: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 72 20 75   statements or u
79c0: 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65  nfinished sqlite
79d0: 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65 63 74 73  3_backup objects
79e0: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6c   then sqlite3_cl
79f0: 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c 20 6c 65  ose().** will le
7a00: 61 76 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ave the database
7a10: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e   connection open
7a20: 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c   and return [SQL
7a30: 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 20 5e 49  ITE_BUSY]..** ^I
7a40: 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  f sqlite3_close_
7a50: 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 77  v2() is called w
7a60: 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a 65 64 20  ith unfinalized 
7a70: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
7a80: 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e 66 69 6e  nts.** and unfin
7a90: 69 73 68 65 64 20 73 71 6c 69 74 65 33 5f 62 61  ished sqlite3_ba
7aa0: 63 6b 75 70 73 2c 20 74 68 65 6e 20 74 68 65 20  ckups, then the 
7ab0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
7ac0: 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a 2a 20 61  ion becomes.** a
7ad0: 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a 6f 6d 62  n unusable "zomb
7ae0: 69 65 22 20 77 68 69 63 68 20 77 69 6c 6c 20 61  ie" which will a
7af0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 65 20  utomatically be 
7b00: 64 65 61 6c 6c 6f 63 61 74 65 64 20 77 68 65 6e  deallocated when
7b10: 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20 70 72 65   the.** last pre
7b20: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
7b30: 69 73 20 66 69 6e 61 6c 69 7a 65 64 20 6f 72 20  is finalized or 
7b40: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
7b50: 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a 20 66 69  _backup is.** fi
7b60: 6e 69 73 68 65 64 2e 20 20 54 68 65 20 73 71 6c  nished.  The sql
7b70: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
7b80: 69 6e 74 65 72 66 61 63 65 20 69 73 20 69 6e 74  interface is int
7b90: 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 77 69  ended for use wi
7ba0: 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61 6e 67 75  th.** host langu
7bb0: 61 67 65 73 20 74 68 61 74 20 61 72 65 20 67 61  ages that are ga
7bc0: 72 62 61 67 65 20 63 6f 6c 6c 65 63 74 65 64 2c  rbage collected,
7bd0: 20 61 6e 64 20 77 68 65 72 65 20 74 68 65 20 6f   and where the o
7be0: 72 64 65 72 20 69 6e 20 77 68 69 63 68 0a 2a 2a  rder in which.**
7bf0: 20 64 65 73 74 72 75 63 74 6f 72 73 20 61 72 65   destructors are
7c00: 20 63 61 6c 6c 65 64 20 69 73 20 61 72 62 69 74   called is arbit
7c10: 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  rary..**.** Appl
7c20: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
7c30: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
7c40: 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c  e | finalize] al
7c50: 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  l [prepared stat
7c60: 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b 73 71 6c  ements],.** [sql
7c70: 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20  ite3_blob_close 
7c80: 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c  | close] all [BL
7c90: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64  OB handles], and
7ca0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61   .** [sqlite3_ba
7cb0: 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c 20 66 69  ckup_finish | fi
7cc0: 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71 6c 69 74  nish] all [sqlit
7cd0: 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63  e3_backup] objec
7ce0: 74 73 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a  ts associated.**
7cf0: 20 77 69 74 68 20 74 68 65 20 5b 73 71 6c 69 74   with the [sqlit
7d00: 65 33 5d 20 6f 62 6a 65 63 74 20 70 72 69 6f 72  e3] object prior
7d10: 20 74 6f 20 61 74 74 65 6d 70 74 69 6e 67 20 74   to attempting t
7d20: 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f 62 6a 65  o close the obje
7d30: 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73 71 6c 69  ct.  ^If.** sqli
7d40: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 69  te3_close_v2() i
7d50: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 64  s called on a [d
7d60: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
7d70: 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c 20 68  on] that still h
7d80: 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64 69 6e  as.** outstandin
7d90: 67 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  g [prepared stat
7da0: 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68  ements], [BLOB h
7db0: 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f 6f 72 0a  andles], and/or.
7dc0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b  ** [sqlite3_back
7dd0: 75 70 5d 20 6f 62 6a 65 63 74 73 20 74 68 65 6e  up] objects then
7de0: 20 69 74 20 72 65 74 75 72 6e 73 20 53 51 4c 49   it returns SQLI
7df0: 54 45 5f 4f 4b 20 62 75 74 20 74 68 65 20 64 65  TE_OK but the de
7e00: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
7e10: 20 72 65 73 6f 75 72 63 65 73 20 69 73 20 64 65   resources is de
7e20: 66 65 72 72 65 64 20 75 6e 74 69 6c 20 61 6c 6c  ferred until all
7e30: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
7e40: 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42 20 68 61  ments], [BLOB ha
7e50: 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e 64 20 5b  ndles],.** and [
7e60: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
7e70: 6f 62 6a 65 63 74 73 20 61 72 65 20 61 6c 73 6f  objects are also
7e80: 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 0a 2a   destroyed..**.*
7e90: 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c 69 74 65  * ^If an [sqlite
7ea0: 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 64 65 73  3] object is des
7eb0: 74 72 6f 79 65 64 20 77 68 69 6c 65 20 61 20 74  troyed while a t
7ec0: 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70  ransaction is op
7ed0: 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73  en,.** the trans
7ee0: 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61  action is automa
7ef0: 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62  tically rolled b
7f00: 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  ack..**.** The C
7f10: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
7f20: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d  qlite3_close(C)]
7f30: 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c   and [sqlite3_cl
7f40: 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a 20 6d 75  ose_v2(C)].** mu
7f50: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
7f60: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
7f70: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
7f80: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
7f90: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
7fa0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
7fb0: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
7fc0: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
7fd0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
7fe0: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
7ff0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
8000: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
8010: 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c 69 74 65  lose() or sqlite
8020: 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20 77 69 74  3_close_v2() wit
8030: 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
8040: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
8050: 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
8060: 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
8070: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
8080: 65 28 73 71 6c 69 74 65 33 2a 29 3b 0a 53 51 4c  e(sqlite3*);.SQL
8090: 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
80a0: 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c  te3_close_v2(sql
80b0: 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54  ite3*);../*.** T
80c0: 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63 61  he type for a ca
80d0: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e  llback function.
80e0: 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67 61  .** This is lega
80f0: 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74 65  cy and deprecate
8100: 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75 64  d.  It is includ
8110: 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61  ed for historica
8120: 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69  l.** compatibili
8130: 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f  ty and is not do
8140: 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70  cumented..*/.typ
8150: 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69 74  edef int (*sqlit
8160: 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69  e3_callback)(voi
8170: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63  d*,int,char**, c
8180: 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  har**);../*.** C
8190: 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65  API3REF: One-Ste
81a0: 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69 6f  p Query Executio
81b0: 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a  n Interface.**.*
81c0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78  * The sqlite3_ex
81d0: 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ec() interface i
81e0: 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20  s a convenience 
81f0: 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a  wrapper around.*
8200: 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
8210: 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74  re_v2()], [sqlit
8220: 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64 20  e3_step()], and 
8230: 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
8240: 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c  e()],.** that al
8250: 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61 74  lows an applicat
8260: 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69  ion to run multi
8270: 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  ple statements o
8280: 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74  f SQL.** without
8290: 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20 61   having to use a
82a0: 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e 20   lot of C code. 
82b0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
82c0: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
82d0: 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f  face runs zero o
82e0: 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e 63  r more UTF-8 enc
82f0: 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c  oded,.** semicol
8300: 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c 20  on-separate SQL 
8310: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
8320: 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20 61  d into its 2nd a
8330: 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74  rgument,.** in t
8340: 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74 68  he context of th
8350: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
8360: 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20 69  ection] passed i
8370: 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a 20  n as its 1st.** 
8380: 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74  argument.  ^If t
8390: 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  he callback func
83a0: 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64 20  tion of the 3rd 
83b0: 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73  argument to.** s
83c0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
83d0: 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
83e0: 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f  it is invoked fo
83f0: 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72 6f  r each result ro
8400: 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20  w.** coming out 
8410: 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65 64  of the evaluated
8420: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
8430: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
8440: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
8450: 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c 61  3_exec() is rela
8460: 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20 74  yed through to t
8470: 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20  he 1st argument 
8480: 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62  of each.** callb
8490: 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20  ack invocation. 
84a0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
84b0: 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c  k pointer to sql
84c0: 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69  ite3_exec().** i
84d0: 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20  s NULL, then no 
84e0: 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65 72  callback is ever
84f0: 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65 73   invoked and res
8500: 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20  ult rows are.** 
8510: 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
8520: 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75  If an error occu
8530: 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74  rs while evaluat
8540: 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61 74  ing the SQL stat
8550: 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e  ements passed in
8560: 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  to.** sqlite3_ex
8570: 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63 75  ec(), then execu
8580: 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72 72  tion of the curr
8590: 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73 74  ent statement st
85a0: 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65  ops and.** subse
85b0: 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 73  quent statements
85c0: 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20 5e   are skipped.  ^
85d0: 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d  If the 5th param
85e0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
85f0: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74  exec().** is not
8600: 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65   NULL then any e
8610: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73 20  rror message is 
8620: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
8630: 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20  ory obtained.** 
8640: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
8650: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73 73  lloc()] and pass
8660: 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68 20  ed back through 
8670: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
8680: 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d  r..** To avoid m
8690: 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68 65  emory leaks, the
86a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
86b0: 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69  uld invoke [sqli
86c0: 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f  te3_free()].** o
86d0: 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20  n error message 
86e0: 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  strings returned
86f0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
8700: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a   parameter of.**
8710: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
8720: 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72 72  () after the err
8730: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
8740: 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e  g is no longer n
8750: 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  eeded..** ^If th
8760: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
8770: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
8780: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e  ) is not NULL an
8790: 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f  d no errors.** o
87a0: 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69 74  ccur, then sqlit
87b0: 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20 74  e3_exec() sets t
87c0: 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69 74  he pointer in it
87d0: 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  s 5th parameter 
87e0: 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72  to.** NULL befor
87f0: 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a  e returning..**.
8800: 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74 65  ** ^If an sqlite
8810: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
8820: 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
8830: 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ro, the sqlite3_
8840: 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  exec().** routin
8850: 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45  e returns SQLITE
8860: 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20 69  _ABORT without i
8870: 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c  nvoking the call
8880: 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a  back again and.*
8890: 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e  * without runnin
88a0: 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e 74  g any subsequent
88b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e   SQL statements.
88c0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20  .**.** ^The 2nd 
88d0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
88e0: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
88f0: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
8900: 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
8910: 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
8920: 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54 68  the result.  ^Th
8930: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
8940: 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78  o the sqlite3_ex
8950: 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  ec().** callback
8960: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20   is an array of 
8970: 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69  pointers to stri
8980: 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73 20  ngs obtained as 
8990: 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69  if from.** [sqli
89a0: 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
89b0: 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63 68  )], one for each
89c0: 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e   column.  ^If an
89d0: 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a   element of a.**
89e0: 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20 4e   result row is N
89f0: 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 72  ULL then the cor
8a00: 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e  responding strin
8a10: 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74 68  g pointer for th
8a20: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  e.** sqlite3_exe
8a30: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  c() callback is 
8a40: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20  a NULL pointer. 
8a50: 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d 65   ^The 4th argume
8a60: 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c  nt to the.** sql
8a70: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
8a80: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
8a90: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
8aa0: 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65 61  strings where ea
8ab0: 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70 72  ch.** entry repr
8ac0: 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65 20  esents the name 
8ad0: 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  of corresponding
8ae0: 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61   result column a
8af0: 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72  s obtained.** fr
8b00: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  om [sqlite3_colu
8b10: 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a  mn_name()]..**.*
8b20: 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70 61  * ^If the 2nd pa
8b30: 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
8b40: 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20 4e  e3_exec() is a N
8b50: 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20 70  ULL pointer, a p
8b60: 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20  ointer.** to an 
8b70: 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f 72  empty string, or
8b80: 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20   a pointer that 
8b90: 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68  contains only wh
8ba0: 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72 20  itespace and/or 
8bb0: 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73  .** SQL comments
8bc0: 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74  , then no SQL st
8bd0: 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76 61  atements are eva
8be0: 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20 64  luated and the d
8bf0: 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f  atabase.** is no
8c00: 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a  t changed..**.**
8c10: 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a   Restrictions:.*
8c20: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
8c30: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
8c40: 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68  n must insure th
8c50: 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61 6d  at the 1st param
8c60: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
8c70: 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20 69  exec().**      i
8c80: 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f 70  s a valid and op
8c90: 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  en [database con
8ca0: 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69  nection]..** <li
8cb0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
8cc0: 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65  n must not close
8cd0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
8ce0: 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64  ction] specified
8cf0: 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65 20   by.**      the 
8d00: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
8d10: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
8d20: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
8d30: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
8d40: 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70 70  .** <li> The app
8d50: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
8d60: 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51 4c  t modify the SQL
8d70: 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
8d80: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 20  passed into.**  
8d90: 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72 61      the 2nd para
8da0: 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
8db0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
8dc0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
8dd0: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c  running..** </ul
8de0: 3e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  >.*/.SQLITE_API 
8df0: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
8e00: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
8e10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8e20: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
8e30: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
8e40: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
8e50: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
8e60: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8e70: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
8e80: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
8e90: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
8ea0: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
8eb0: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
8ec0: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
8ed0: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
8ee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8ef0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
8f00: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
8f10: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
8f20: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
8f30: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
8f40: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
8f50: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
8f60: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
8f70: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
8f80: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
8f90: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
8fa0: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
8fb0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
8fc0: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
8fd0: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
8fe0: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
8ff0: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
9000: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
9010: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
9020: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
9030: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
9040: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
9050: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
9060: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
9070: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
9080: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
9090: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
90a0: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
90b0: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
90c0: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
90d0: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
90e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
90f0: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
9100: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
9110: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
9120: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
9130: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
9140: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
9150: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
9160: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
9170: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
9180: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
9190: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
91a0: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
91b0: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
91c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
91d0: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
91e0: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
91f0: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
9200: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
9210: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
9220: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
9230: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
9240: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
9250: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
9260: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
9270: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
9280: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
9290: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
92a0: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
92b0: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
92c0: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
92d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
92e0: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
92f0: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
9300: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
9310: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
9320: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
9330: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
9340: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
9350: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9360: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
9370: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
9380: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
9390: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
93a0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
93b0: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
93c0: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
93d0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
93e0: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
93f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
9400: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
9410: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
9420: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
9430: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
9440: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
9450: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
9460: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
9470: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
9480: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
9490: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
94a0: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
94b0: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
94c0: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
94d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
94e0: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
94f0: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
9500: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
9510: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
9520: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
9530: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
9540: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
9550: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
9560: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
9570: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
9580: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
9590: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
95a0: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
95b0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
95c0: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
95d0: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
95e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
95f0: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
9600: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
9610: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
9620: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
9630: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
9640: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
9650: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
9660: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
9670: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
9680: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
9690: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
96a0: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
96b0: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
96c0: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
96d0: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
96e0: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
96f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
9700: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
9710: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
9720: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
9730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
9740: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
9750: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
9760: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
9770: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
9780: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
9790: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
97a0: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
97b0: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
97c0: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
97d0: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
97e0: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
97f0: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
9800: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
9810: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
9820: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
9830: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
9840: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
9850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
9860: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
9870: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
9880: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
9890: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
98a0: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
98b0: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
98c0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
98d0: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
98e0: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
98f0: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
9900: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
9910: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
9920: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
9930: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
9940: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
9950: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
9960: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
9970: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
9980: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
9990: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
99a0: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
99b0: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
99c0: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
99d0: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
99e0: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
99f0: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
9a00: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
9a10: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
9a20: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
9a30: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
9a40: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
9a50: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
9a60: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
9a70: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
9a80: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
9a90: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
9aa0: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
9ab0: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
9ac0: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
9ad0: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
9ae0: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
9af0: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
9b00: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
9b10: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
9b20: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
9b30: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
9b40: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
9b50: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
9b60: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
9b70: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
9b80: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
9b90: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
9ba0: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
9bb0: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
9bc0: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
9bd0: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
9be0: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
9bf0: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
9c00: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
9c10: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
9c20: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
9c30: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
9c40: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
9c50: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
9c60: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
9c70: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
9c80: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
9c90: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
9ca0: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
9cb0: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
9cc0: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
9cd0: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
9ce0: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
9cf0: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
9d00: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
9d10: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
9d20: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
9d30: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
9d40: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
9d50: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
9d60: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
9d70: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
9d80: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
9d90: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
9da0: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
9db0: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
9dc0: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
9dd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
9de0: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
9df0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
9e00: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
9e10: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
9e20: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
9e30: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
9e40: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
9e50: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
9e60: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
9e70: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
9e80: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
9e90: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
9ea0: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
9eb0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
9ec0: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
9ed0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
9ee0: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
9ef0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9f00: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
9f10: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
9f20: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
9f30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
9f40: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
9f50: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
9f60: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
9f70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
9f80: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
9f90: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
9fa0: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
9fb0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
9fc0: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
9fd0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
9fe0: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
9ff0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a000: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
a010: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a020: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
a030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a040: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
a050: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a060: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
a070: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a080: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
a090: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a0a0: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
a0b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a0c0: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
a0d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a0e0: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
a0f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a100: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
a110: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
a120: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
a130: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a140: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
a150: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a160: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
a170: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a180: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
a190: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a1a0: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
a1b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a1c0: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
a1d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a1e0: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
a1f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a200: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
a210: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a220: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
a230: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a240: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
a250: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a260: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
a270: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a280: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
a290: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a2a0: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
a2b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a2c0: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
a2d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a2e0: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
a2f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a300: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
a310: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a320: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
a330: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
a340: 52 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20  R_DELETE_NOENT  
a350: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
a360: 52 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65  R | (23<<8)).#de
a370: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
a380: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
a390: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
a3a0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
a3b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
a3c0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
a3d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
a3e0: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
a3f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
a400: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
a410: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
a420: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
a430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
a440: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
a450: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
a460: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
a470: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a480: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
a490: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
a4a0: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
a4b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
a4c0: 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42  ITE_CORRUPT_VTAB
a4d0: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
a4e0: 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31  ITE_CORRUPT | (1
a4f0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
a500: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45  LITE_READONLY_RE
a510: 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51  COVERY       (SQ
a520: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
a530: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
a540: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
a550: 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28  CANTLOCK       (
a560: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
a570: 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (2<<8)).#defin
a580: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
a590: 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  Y_ROLLBACK      
a5a0: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
a5b0: 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66  Y | (3<<8)).#def
a5c0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54  ine SQLITE_ABORT
a5d0: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
a5e0: 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52 54     (SQLITE_ABORT
a5f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
a600: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
a610: 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20 20  AINT_CHECK      
a620: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
a630: 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a 23  AINT | (1<<8)).#
a640: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
a650: 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54 48  NSTRAINT_COMMITH
a660: 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  OOK   (SQLITE_CO
a670: 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c 38  NSTRAINT | (2<<8
a680: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a690: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f 52  E_CONSTRAINT_FOR
a6a0: 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49 54  EIGNKEY   (SQLIT
a6b0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
a6c0: 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  3<<8)).#define S
a6d0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
a6e0: 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28 53  _FUNCTION     (S
a6f0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
a700: 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66 69   | (4<<8)).#defi
a710: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
a720: 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20 20  AINT_NOTNULL    
a730: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
a740: 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a 23  AINT | (5<<8)).#
a750: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
a760: 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52 59  NSTRAINT_PRIMARY
a770: 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43 4f  KEY   (SQLITE_CO
a780: 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c 38  NSTRAINT | (6<<8
a790: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
a7a0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52 49  E_CONSTRAINT_TRI
a7b0: 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49 54  GGER      (SQLIT
a7c0: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
a7d0: 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  7<<8)).#define S
a7e0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
a7f0: 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28 53  _UNIQUE       (S
a800: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
a810: 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69   | (8<<8)).#defi
a820: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
a830: 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20 20  AINT_VTAB       
a840: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
a850: 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a 0a  AINT | (9<<8))..
a860: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
a870: 46 6c 61 67 73 20 46 6f 72 20 46 69 6c 65 20 4f  Flags For File O
a880: 70 65 6e 20 4f 70 65 72 61 74 69 6f 6e 73 0a 2a  pen Operations.*
a890: 2a 0a 2a 2a 20 54 68 65 73 65 20 62 69 74 20 76  *.** These bit v
a8a0: 61 6c 75 65 73 20 61 72 65 20 69 6e 74 65 6e 64  alues are intend
a8b0: 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 74 68  ed for use in th
a8c0: 65 0a 2a 2a 20 33 72 64 20 70 61 72 61 6d 65 74  e.** 3rd paramet
a8d0: 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  er to the [sqlit
a8e0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69 6e  e3_open_v2()] in
a8f0: 74 65 72 66 61 63 65 20 61 6e 64 0a 2a 2a 20 69  terface and.** i
a900: 6e 20 74 68 65 20 34 74 68 20 70 61 72 61 6d 65  n the 4th parame
a910: 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
a920: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d  te3_vfs.xOpen] m
a930: 65 74 68 6f 64 2e 0a 2a 2f 0a 23 64 65 66 69 6e  ethod..*/.#defin
a940: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
a950: 41 44 4f 4e 4c 59 20 20 20 20 20 20 20 20 20 30  ADONLY         0
a960: 78 30 30 30 30 30 30 30 31 20 20 2f 2a 20 4f 6b  x00000001  /* Ok
a970: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
a980: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
a990: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  e SQLITE_OPEN_RE
a9a0: 41 44 57 52 49 54 45 20 20 20 20 20 20 20 20 30  ADWRITE        0
a9b0: 78 30 30 30 30 30 30 30 32 20 20 2f 2a 20 4f 6b  x00000002  /* Ok
a9c0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
a9d0: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
a9e0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  e SQLITE_OPEN_CR
a9f0: 45 41 54 45 20 20 20 20 20 20 20 20 20 20 20 30  EATE           0
aa00: 78 30 30 30 30 30 30 30 34 20 20 2f 2a 20 4f 6b  x00000004  /* Ok
aa10: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
aa20: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
aa30: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45  e SQLITE_OPEN_DE
aa40: 4c 45 54 45 4f 4e 43 4c 4f 53 45 20 20 20 20 30  LETEONCLOSE    0
aa50: 78 30 30 30 30 30 30 30 38 20 20 2f 2a 20 56 46  x00000008  /* VF
aa60: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
aa70: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
aa80: 43 4c 55 53 49 56 45 20 20 20 20 20 20 20 20 30  CLUSIVE        0
aa90: 78 30 30 30 30 30 30 31 30 20 20 2f 2a 20 56 46  x00000010  /* VF
aaa0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
aab0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 41 55  e SQLITE_OPEN_AU
aac0: 54 4f 50 52 4f 58 59 20 20 20 20 20 20 20 20 30  TOPROXY        0
aad0: 78 30 30 30 30 30 30 32 30 20 20 2f 2a 20 56 46  x00000020  /* VF
aae0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
aaf0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52  e SQLITE_OPEN_UR
ab00: 49 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  I              0
ab10: 78 30 30 30 30 30 30 34 30 20 20 2f 2a 20 4f 6b  x00000040  /* Ok
ab20: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
ab30: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
ab40: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 45  e SQLITE_OPEN_ME
ab50: 4d 4f 52 59 20 20 20 20 20 20 20 20 20 20 20 30  MORY           0
ab60: 78 30 30 30 30 30 30 38 30 20 20 2f 2a 20 4f 6b  x00000080  /* Ok
ab70: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
ab80: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
ab90: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
aba0: 49 4e 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  IN_DB          0
abb0: 78 30 30 30 30 30 31 30 30 20 20 2f 2a 20 56 46  x00000100  /* VF
abc0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
abd0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
abe0: 4d 50 5f 44 42 20 20 20 20 20 20 20 20 20 20 30  MP_DB          0
abf0: 78 30 30 30 30 30 32 30 30 20 20 2f 2a 20 56 46  x00000200  /* VF
ac00: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
ac10: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52  e SQLITE_OPEN_TR
ac20: 41 4e 53 49 45 4e 54 5f 44 42 20 20 20 20 20 30  ANSIENT_DB     0
ac30: 78 30 30 30 30 30 34 30 30 20 20 2f 2a 20 56 46  x00000400  /* VF
ac40: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
ac50: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
ac60: 49 4e 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  IN_JOURNAL     0
ac70: 78 30 30 30 30 30 38 30 30 20 20 2f 2a 20 56 46  x00000800  /* VF
ac80: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
ac90: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45  e SQLITE_OPEN_TE
aca0: 4d 50 5f 4a 4f 55 52 4e 41 4c 20 20 20 20 20 30  MP_JOURNAL     0
acb0: 78 30 30 30 30 31 30 30 30 20 20 2f 2a 20 56 46  x00001000  /* VF
acc0: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
acd0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55  e SQLITE_OPEN_SU
ace0: 42 4a 4f 55 52 4e 41 4c 20 20 20 20 20 20 20 30  BJOURNAL       0
acf0: 78 30 30 30 30 32 30 30 30 20 20 2f 2a 20 56 46  x00002000  /* VF
ad00: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
ad10: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41  e SQLITE_OPEN_MA
ad20: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 20 20 20 30  STER_JOURNAL   0
ad30: 78 30 30 30 30 34 30 30 30 20 20 2f 2a 20 56 46  x00004000  /* VF
ad40: 53 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  S only */.#defin
ad50: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f  e SQLITE_OPEN_NO
ad60: 4d 55 54 45 58 20 20 20 20 20 20 20 20 20 20 30  MUTEX          0
ad70: 78 30 30 30 30 38 30 30 30 20 20 2f 2a 20 4f 6b  x00008000  /* Ok
ad80: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
ad90: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
ada0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55  e SQLITE_OPEN_FU
adb0: 4c 4c 4d 55 54 45 58 20 20 20 20 20 20 20 20 30  LLMUTEX        0
adc0: 78 30 30 30 31 30 30 30 30 20 20 2f 2a 20 4f 6b  x00010000  /* Ok
add0: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
ade0: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
adf0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48  e SQLITE_OPEN_SH
ae00: 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20 30  AREDCACHE      0
ae10: 78 30 30 30 32 30 30 30 30 20 20 2f 2a 20 4f 6b  x00020000  /* Ok
ae20: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
ae30: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
ae40: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52  e SQLITE_OPEN_PR
ae50: 49 56 41 54 45 43 41 43 48 45 20 20 20 20 20 30  IVATECACHE     0
ae60: 78 30 30 30 34 30 30 30 30 20 20 2f 2a 20 4f 6b  x00040000  /* Ok
ae70: 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65   for sqlite3_ope
ae80: 6e 5f 76 32 28 29 20 2a 2f 0a 23 64 65 66 69 6e  n_v2() */.#defin
ae90: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57 41  e SQLITE_OPEN_WA
aea0: 4c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  L              0
aeb0: 78 30 30 30 38 30 30 30 30 20 20 2f 2a 20 56 46  x00080000  /* VF
aec0: 53 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 20 52 65  S only */../* Re
aed0: 73 65 72 76 65 64 3a 20 20 20 20 20 20 20 20 20  served:         
aee0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
aef0: 30 78 30 30 46 30 30 30 30 30 20 2a 2f 0a 0a 2f  0x00F00000 */../
af00: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
af10: 65 76 69 63 65 20 43 68 61 72 61 63 74 65 72 69  evice Characteri
af20: 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  stics.**.** The 
af30: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
af40: 69 73 74 69 63 73 20 6d 65 74 68 6f 64 20 6f 66  istics method of
af50: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
af60: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 6f 62 6a  _methods].** obj
af70: 65 63 74 20 72 65 74 75 72 6e 73 20 61 6e 20 69  ect returns an i
af80: 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73 20  nteger which is 
af90: 61 20 76 65 63 74 6f 72 20 6f 66 20 74 68 65 73  a vector of thes
afa0: 65 0a 2a 2a 20 62 69 74 20 76 61 6c 75 65 73 20  e.** bit values 
afb0: 65 78 70 72 65 73 73 69 6e 67 20 49 2f 4f 20 63  expressing I/O c
afc0: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6f  haracteristics o
afd0: 66 20 74 68 65 20 6d 61 73 73 20 73 74 6f 72 61  f the mass stora
afe0: 67 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61  ge.** device tha
aff0: 74 20 68 6f 6c 64 73 20 74 68 65 20 66 69 6c 65  t holds the file
b000: 20 74 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74   that the [sqlit
b010: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a  e3_io_methods].*
b020: 2a 20 72 65 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a  * refers to..**.
b030: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  ** The SQLITE_IO
b040: 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65  CAP_ATOMIC prope
b050: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61  rty means that a
b060: 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20  ll writes of.** 
b070: 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f  any size are ato
b080: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
b090: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e  _IOCAP_ATOMICnnn
b0a0: 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20   values.** mean 
b0b0: 74 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62  that writes of b
b0c0: 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e  locks that are n
b0d0: 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65  nn bytes in size
b0e0: 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67   and.** are alig
b0f0: 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73  ned to an addres
b100: 73 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e  s which is an in
b110: 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f  teger multiple o
b120: 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f  f.** nnn are ato
b130: 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45  mic.  The SQLITE
b140: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
b150: 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a  ND value means.*
b160: 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61  * that when data
b170: 20 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20   is appended to 
b180: 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61  a file, the data
b190: 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20   is appended.** 
b1a0: 66 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73  first then the s
b1b0: 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20  ize of the file 
b1c0: 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76  is extended, nev
b1d0: 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  er the other.** 
b1e0: 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65  way around.  The
b1f0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
b200: 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74  QUENTIAL propert
b210: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
b220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77  information is w
b230: 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69  ritten to disk i
b240: 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72  n the same order
b250: 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20   as calls.** to 
b260: 78 57 72 69 74 65 28 29 2e 20 20 54 68 65 20 53  xWrite().  The S
b270: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
b280: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
b290: 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74  property means t
b2a0: 68 61 74 0a 2a 2a 20 61 66 74 65 72 20 72 65 62  hat.** after reb
b2b0: 6f 6f 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  oot following a 
b2c0: 63 72 61 73 68 20 6f 72 20 70 6f 77 65 72 20 6c  crash or power l
b2d0: 6f 73 73 2c 20 74 68 65 20 6f 6e 6c 79 20 62 79  oss, the only by
b2e0: 74 65 73 20 69 6e 20 61 0a 2a 2a 20 66 69 6c 65  tes in a.** file
b2f0: 20 74 68 61 74 20 77 65 72 65 20 77 72 69 74 74   that were writt
b300: 65 6e 20 61 74 20 74 68 65 20 61 70 70 6c 69 63  en at the applic
b310: 61 74 69 6f 6e 20 6c 65 76 65 6c 20 6d 69 67 68  ation level migh
b320: 74 20 68 61 76 65 20 63 68 61 6e 67 65 64 0a 2a  t have changed.*
b330: 2a 20 61 6e 64 20 74 68 61 74 20 61 64 6a 61 63  * and that adjac
b340: 65 6e 74 20 62 79 74 65 73 2c 20 65 76 65 6e 20  ent bytes, even 
b350: 62 79 74 65 73 20 77 69 74 68 69 6e 20 74 68 65  bytes within the
b360: 20 73 61 6d 65 20 73 65 63 74 6f 72 20 61 72 65   same sector are
b370: 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65 64 20 74  .** guaranteed t
b380: 6f 20 62 65 20 75 6e 63 68 61 6e 67 65 64 2e 0a  o be unchanged..
b390: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
b3a0: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 20  E_IOCAP_ATOMIC  
b3b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
b3c0: 78 30 30 30 30 30 30 30 31 0a 23 64 65 66 69 6e  x00000001.#defin
b3d0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
b3e0: 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20 20 20  TOMIC512        
b3f0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
b400: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b410: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b 20 20  IOCAP_ATOMIC1K  
b420: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
b430: 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e 65 20  0000004.#define 
b440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
b450: 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20 20 20  MIC2K           
b460: 20 20 20 20 30 78 30 30 30 30 30 30 30 38 0a 23      0x00000008.#
b470: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
b480: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20 20 20  CAP_ATOMIC4K    
b490: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
b4a0: 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20 53 51  00010.#define SQ
b4b0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
b4c0: 43 38 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C8K             
b4d0: 20 20 30 78 30 30 30 30 30 30 32 30 0a 23 64 65    0x00000020.#de
b4e0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
b4f0: 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20 20 20  P_ATOMIC16K     
b500: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
b510: 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  040.#define SQLI
b520: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 33  TE_IOCAP_ATOMIC3
b530: 32 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  2K              
b540: 30 78 30 30 30 30 30 30 38 30 0a 23 64 65 66 69  0x00000080.#defi
b550: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
b560: 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20 20 20  ATOMIC64K       
b570: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
b580: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b590: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
b5a0: 4e 44 20 20 20 20 20 20 20 20 20 20 20 20 30 78  ND            0x
b5b0: 30 30 30 30 30 32 30 30 0a 23 64 65 66 69 6e 65  00000200.#define
b5c0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45   SQLITE_IOCAP_SE
b5d0: 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20 20 20  QUENTIAL        
b5e0: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 0a       0x00000400.
b5f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
b600: 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42 4c 45  OCAP_UNDELETABLE
b610: 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78 30 30  _WHEN_OPEN  0x00
b620: 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65 20 53  000800.#define S
b630: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
b640: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 20  RSAFE_OVERWRITE 
b650: 20 20 20 30 78 30 30 30 30 31 30 30 30 0a 0a 2f     0x00001000../
b660: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
b670: 69 6c 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65  ile Locking Leve
b680: 6c 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  ls.**.** SQLite 
b690: 75 73 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73  uses one of thes
b6a0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
b6b0: 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
b6c0: 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61  * argument to ca
b6d0: 6c 6c 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20  lls it makes to 
b6e0: 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20  the xLock() and 
b6f0: 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  xUnlock() method
b700: 73 0a 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69  s.** of an [sqli
b710: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
b720: 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69  object..*/.#defi
b730: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e  ne SQLITE_LOCK_N
b740: 4f 4e 45 20 20 20 20 20 20 20 20 20 20 30 0a 23  ONE          0.#
b750: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
b760: 43 4b 5f 53 48 41 52 45 44 20 20 20 20 20 20 20  CK_SHARED       
b770: 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
b780: 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20  E_LOCK_RESERVED 
b790: 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
b7a0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49  QLITE_LOCK_PENDI
b7b0: 4e 47 20 20 20 20 20 20 20 33 0a 23 64 65 66 69  NG       3.#defi
b7c0: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  ne SQLITE_LOCK_E
b7d0: 58 43 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a  XCLUSIVE     4..
b7e0: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
b7f0: 53 79 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20  Synchronization 
b800: 54 79 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a  Type Flags.**.**
b810: 20 57 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76   When SQLite inv
b820: 6f 6b 65 73 20 74 68 65 20 78 53 79 6e 63 28 29  okes the xSync()
b830: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a   method of an.**
b840: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
b850: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20  hods] object it 
b860: 75 73 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69  uses a combinati
b870: 6f 6e 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69  on of.** these i
b880: 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73  nteger values as
b890: 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
b8a0: 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e  ment..**.** When
b8b0: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
b8c0: 5f 44 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69  _DATAONLY flag i
b8d0: 73 20 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73  s used, it means
b8e0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e   that the.** syn
b8f0: 63 20 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79  c operation only
b900: 20 6e 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20   needs to flush 
b910: 64 61 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f  data to mass sto
b920: 72 61 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20  rage.  Inode.** 
b930: 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64  information need
b940: 20 6e 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e   not be flushed.
b950: 20 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f   If the lower fo
b960: 75 72 20 62 69 74 73 20 6f 66 20 74 68 65 20 66  ur bits of the f
b970: 6c 61 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c  lag.** equal SQL
b980: 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c  ITE_SYNC_NORMAL,
b990: 20 74 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75   that means to u
b9a0: 73 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  se normal fsync(
b9b0: 29 20 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20  ) semantics..** 
b9c0: 49 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75  If the lower fou
b9d0: 72 20 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c  r bits equal SQL
b9e0: 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74  ITE_SYNC_FULL, t
b9f0: 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20  hat means.** to 
ba00: 75 73 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79  use Mac OS X sty
ba10: 6c 65 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74  le fullsync inst
ba20: 65 61 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a  ead of fsync()..
ba30: 2a 2a 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e  **.** Do not con
ba40: 66 75 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f  fuse the SQLITE_
ba50: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20  SYNC_NORMAL and 
ba60: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
ba70: 20 66 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74   flags.** with t
ba80: 68 65 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  he [PRAGMA synch
ba90: 72 6f 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61  ronous]=NORMAL a
baa0: 6e 64 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  nd [PRAGMA synch
bab0: 72 6f 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20  ronous]=FULL.** 
bac0: 73 65 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b  settings.  The [
bad0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67  synchronous prag
bae0: 6d 61 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77  ma] determines w
baf0: 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  hen calls to the
bb00: 0a 2a 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65  .** xSync VFS me
bb10: 74 68 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61  thod occur and a
bb20: 70 70 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79  pplies uniformly
bb30: 20 61 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74   across all plat
bb40: 66 6f 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51  forms..** The SQ
bb50: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
bb60: 20 61 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43   and SQLITE_SYNC
bb70: 5f 46 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65  _FULL flags dete
bb80: 72 6d 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65  rmine how.** ene
bb90: 72 67 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f  rgetic or rigoro
bba0: 75 73 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74  us or forceful t
bbb0: 68 65 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f  he sync operatio
bbc0: 6e 73 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e  ns are and.** on
bbd0: 6c 79 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72  ly make a differ
bbe0: 65 6e 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20  ence on Mac OSX 
bbf0: 66 6f 72 20 74 68 65 20 64 65 66 61 75 6c 74 20  for the default 
bc00: 53 51 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20  SQLite code..** 
bc10: 28 54 68 69 72 64 2d 70 61 72 74 79 20 56 46 53  (Third-party VFS
bc20: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
bc30: 20 6d 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65   might also make
bc40: 20 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e   the distinction
bc50: 0a 2a 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49  .** between SQLI
bc60: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
bc70: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
bc80: 55 4c 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74  ULL, but among t
bc90: 68 65 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20  he.** operating 
bca0: 73 79 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79  systems natively
bcb0: 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53 51   supported by SQ
bcc0: 4c 69 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f  Lite, only Mac O
bcd0: 53 58 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75  SX.** cares abou
bce0: 74 20 74 68 65 20 64 69 66 66 65 72 65 6e 63 65  t the difference
bcf0: 2e 29 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  .).*/.#define SQ
bd00: 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c  LITE_SYNC_NORMAL
bd10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 32 0a          0x00002.
bd20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
bd30: 59 4e 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20  YNC_FULL        
bd40: 20 20 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e    0x00003.#defin
bd50: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41  e SQLITE_SYNC_DA
bd60: 54 41 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30  TAONLY      0x00
bd70: 30 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  010../*.** CAPI3
bd80: 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63  REF: OS Interfac
bd90: 65 20 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64  e Open File Hand
bda0: 6c 65 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c  le.**.** An [sql
bdb0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
bdc0: 74 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  t represents an 
bdd0: 6f 70 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65  open file in the
bde0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66   .** [sqlite3_vf
bdf0: 73 20 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65  s | OS interface
be00: 20 6c 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69   layer].  Indivi
be10: 64 75 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63  dual OS interfac
be20: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
be30: 69 6f 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e  ions will.** wan
be40: 74 20 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68  t to subclass th
be50: 69 73 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70  is object by app
be60: 65 6e 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61  ending additiona
be70: 6c 20 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20  l fields.** for 
be80: 74 68 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20  their own use.  
be90: 54 68 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74  The pMethods ent
bea0: 72 79 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ry is a pointer 
beb0: 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65  to an.** [sqlite
bec0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
bed0: 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
bee0: 73 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65  s methods for pe
bef0: 72 66 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20  rforming.** I/O 
bf00: 6f 70 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68  operations on th
bf10: 65 20 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a  e open file..*/.
bf20: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
bf30: 71 6c 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69  qlite3_file sqli
bf40: 74 65 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74  te3_file;.struct
bf50: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a   sqlite3_file {.
bf60: 20 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73    const struct s
bf70: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
bf80: 73 20 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a  s *pMethods;  /*
bf90: 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20   Methods for an 
bfa0: 6f 70 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a  open file */.};.
bfb0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
bfc0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 46 69   OS Interface Fi
bfd0: 6c 65 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f  le Virtual Metho
bfe0: 64 73 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  ds Object.**.** 
bff0: 45 76 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65  Every file opene
c000: 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
c010: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74  3_vfs.xOpen] met
c020: 68 6f 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e  hod populates an
c030: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
c040: 65 5d 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d  e] object (or, m
c050: 6f 72 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20  ore commonly, a 
c060: 73 75 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a  subclass of the.
c070: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
c080: 5d 20 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61  ] object) with a
c090: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
c0a0: 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20  nstance of this 
c0b0: 6f 62 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20  object..** This 
c0c0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
c0d0: 68 65 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20  he methods used 
c0e0: 74 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f  to perform vario
c0f0: 75 73 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a  us operations.**
c100: 20 61 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65   against the ope
c110: 6e 20 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74  n file represent
c120: 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
c130: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e  e3_file] object.
c140: 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73  .**.** If the [s
c150: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
c160: 5d 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  ] method sets th
c170: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
c180: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
c190: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
c1a0: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
c1b0: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
c1c0: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
c1d0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
c1e0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
c1f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
c200: 78 4f 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20  xOpen] reported 
c210: 74 68 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20  that it failed. 
c220: 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79   The.** only way
c230: 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61   to prevent a ca
c240: 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c  ll to xClose fol
c250: 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20  lowing a failed 
c260: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
c270: 65 6e 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68  en].** is for th
c280: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
c290: 4f 70 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65  Open] to set the
c2a0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
c2b0: 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a  ethods element.*
c2c0: 2a 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  * to NULL..**.**
c2d0: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
c2e0: 65 6e 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79  ent to xSync may
c2f0: 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   be one of [SQLI
c300: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20  TE_SYNC_NORMAL] 
c310: 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59  or.** [SQLITE_SY
c320: 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66  NC_FULL].  The f
c330: 69 72 73 74 20 63 68 6f 69 63 65 20 69 73 20 74  irst choice is t
c340: 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28  he normal fsync(
c350: 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  )..** The second
c360: 20 63 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63   choice is a Mac
c370: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
c380: 73 79 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49  sync.  The [SQLI
c390: 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59  TE_SYNC_DATAONLY
c3a0: 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65  ].** flag may be
c3b0: 20 4f 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69   ORed in to indi
c3c0: 63 61 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74  cate that only t
c3d0: 68 65 20 64 61 74 61 20 6f 66 20 74 68 65 20 66  he data of the f
c3e0: 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69  ile.** and not i
c3f0: 74 73 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74  ts inode needs t
c400: 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a  o be synced..**.
c410: 2a 2a 20 54 68 65 20 69 6e 74 65 67 65 72 20 76  ** The integer v
c420: 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29  alues to xLock()
c430: 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61   and xUnlock() a
c440: 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c  re one of.** <ul
c450: 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  >.** <li> [SQLIT
c460: 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a  E_LOCK_NONE],.**
c470: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
c480: 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c  CK_SHARED],.** <
c490: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
c4a0: 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c  _RESERVED],.** <
c4b0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
c4c0: 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a  _PENDING], or.**
c4d0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
c4e0: 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a  CK_EXCLUSIVE]..*
c4f0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b  * </ul>.** xLock
c500: 28 29 20 69 6e 63 72 65 61 73 65 73 20 74 68 65  () increases the
c510: 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29   lock. xUnlock()
c520: 20 64 65 63 72 65 61 73 65 73 20 74 68 65 20 6c   decreases the l
c530: 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65  ock..** The xChe
c540: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29  ckReservedLock()
c550: 20 6d 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77   method checks w
c560: 68 65 74 68 65 72 20 61 6e 79 20 64 61 74 61 62  hether any datab
c570: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a  ase connection,.
c580: 2a 2a 20 65 69 74 68 65 72 20 69 6e 20 74 68 69  ** either in thi
c590: 73 20 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20  s process or in 
c5a0: 73 6f 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65  some other proce
c5b0: 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61  ss, is holding a
c5c0: 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45   RESERVED,.** PE
c5d0: 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53  NDING, or EXCLUS
c5e0: 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20  IVE lock on the 
c5f0: 66 69 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e  file.  It return
c600: 73 20 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63  s true.** if suc
c610: 68 20 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20  h a lock exists 
c620: 61 6e 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77  and false otherw
c630: 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ise..**.** The x
c640: 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65  FileControl() me
c650: 74 68 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69  thod is a generi
c660: 63 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  c interface that
c670: 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a   allows custom.*
c680: 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  * VFS implementa
c690: 74 69 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c  tions to directl
c6a0: 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65  y control an ope
c6b0: 6e 20 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65  n file using the
c6c0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
c6d0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74  e_control()] int
c6e0: 65 72 66 61 63 65 2e 20 20 54 68 65 20 73 65 63  erface.  The sec
c6f0: 6f 6e 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e  ond "op" argumen
c700: 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67  t is an.** integ
c710: 65 72 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20  er opcode.  The 
c720: 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
c730: 73 20 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e  s a generic poin
c740: 74 65 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a  ter intended to.
c750: 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  ** point to a st
c760: 72 75 63 74 75 72 65 20 74 68 61 74 20 6d 61 79  ructure that may
c770: 20 63 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e   contain argumen
c780: 74 73 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77  ts or space in w
c790: 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65  hich to.** write
c7a0: 20 72 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20   return values. 
c7b0: 20 50 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20   Potential uses 
c7c0: 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  for xFileControl
c7d0: 28 29 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66  () might be.** f
c7e0: 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62  unctions to enab
c7f0: 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b  le blocking lock
c800: 73 20 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c  s with timeouts,
c810: 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a   to change the.*
c820: 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65  * locking strate
c830: 67 79 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20  gy (for example 
c840: 74 6f 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20  to use dot-file 
c850: 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69  locks), to inqui
c860: 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20  re.** about the 
c870: 73 74 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b  status of a lock
c880: 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74  , or to break st
c890: 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20  ale locks.  The 
c8a0: 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72  SQLite.** core r
c8b0: 65 73 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f  eserves all opco
c8c0: 64 65 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30  des less than 10
c8d0: 30 20 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73  0 for its own us
c8e0: 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f  e..** A [SQLITE_
c8f0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
c900: 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65  | list of opcode
c910: 73 5d 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30  s] less than 100
c920: 20 69 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a   is available..*
c930: 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  * Applications t
c940: 68 61 74 20 64 65 66 69 6e 65 20 61 20 63 75 73  hat define a cus
c950: 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  tom xFileControl
c960: 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75   method should u
c970: 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72  se opcodes.** gr
c980: 65 61 74 65 72 20 74 68 61 6e 20 31 30 30 20 74  eater than 100 t
c990: 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74  o avoid conflict
c9a0: 73 2e 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e  s.  VFS implemen
c9b0: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a  tations should.*
c9c0: 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
c9d0: 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66  _NOTFOUND] for f
c9e0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
c9f0: 64 65 73 20 74 68 61 74 20 74 68 65 79 20 64 6f  des that they do
ca00: 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a   not.** recogniz
ca10: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65  e..**.** The xSe
ca20: 63 74 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f  ctorSize() metho
ca30: 64 20 72 65 74 75 72 6e 73 20 74 68 65 20 73 65  d returns the se
ca40: 63 74 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65  ctor size of the
ca50: 0a 2a 2a 20 64 65 76 69 63 65 20 74 68 61 74 20  .** device that 
ca60: 75 6e 64 65 72 6c 69 65 73 20 74 68 65 20 66 69  underlies the fi
ca70: 6c 65 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20  le.  The sector 
ca80: 73 69 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d  size is the.** m
ca90: 69 6e 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61  inimum write tha
caa0: 74 20 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d  t can be perform
cab0: 65 64 20 77 69 74 68 6f 75 74 20 64 69 73 74 75  ed without distu
cac0: 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62  rbing.** other b
cad0: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
cae0: 2e 20 20 54 68 65 20 78 44 65 76 69 63 65 43 68  .  The xDeviceCh
caf0: 61 72 61 63 74 65 72 69 73 74 69 63 73 28 29 0a  aracteristics().
cb00: 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e  ** method return
cb10: 73 20 61 20 62 69 74 20 76 65 63 74 6f 72 20 64  s a bit vector d
cb20: 65 73 63 72 69 62 69 6e 67 20 62 65 68 61 76 69  escribing behavi
cb30: 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e  ors of the.** un
cb40: 64 65 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a  derlying device:
cb50: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
cb60: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
cb70: 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69  P_ATOMIC].** <li
cb80: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
cb90: 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c  ATOMIC512].** <l
cba0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
cbb0: 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC1K].** <l
cbc0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
cbd0: 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC2K].** <l
cbe0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
cbf0: 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC4K].** <l
cc00: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
cc10: 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c  _ATOMIC8K].** <l
cc20: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
cc30: 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c  _ATOMIC16K].** <
cc40: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
cc50: 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20  P_ATOMIC32K].** 
cc60: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
cc70: 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a  AP_ATOMIC64K].**
cc80: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
cc90: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d  CAP_SAFE_APPEND]
cca0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
ccb0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
ccc0: 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  L].** </ul>.**.*
ccd0: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43  * The SQLITE_IOC
cce0: 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72  AP_ATOMIC proper
ccf0: 74 79 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c  ty means that al
cd00: 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61  l writes of.** a
cd10: 6e 79 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d  ny size are atom
cd20: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
cd30: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20  IOCAP_ATOMICnnn 
cd40: 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74  values.** mean t
cd50: 68 61 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c  hat writes of bl
cd60: 6f 63 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e  ocks that are nn
cd70: 6e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20  n bytes in size 
cd80: 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e  and.** are align
cd90: 65 64 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73  ed to an address
cda0: 20 77 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74   which is an int
cdb0: 65 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66  eger multiple of
cdc0: 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d  .** nnn are atom
cdd0: 69 63 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  ic.  The SQLITE_
cde0: 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e  IOCAP_SAFE_APPEN
cdf0: 44 20 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a  D value means.**
ce00: 20 74 68 61 74 20 77 68 65 6e 20 64 61 74 61 20   that when data 
ce10: 69 73 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61  is appended to a
ce20: 20 66 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20   file, the data 
ce30: 69 73 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66  is appended.** f
ce40: 69 72 73 74 20 74 68 65 6e 20 74 68 65 20 73 69  irst then the si
ce50: 7a 65 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69  ze of the file i
ce60: 73 20 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65  s extended, neve
ce70: 72 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77  r the other.** w
ce80: 61 79 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20  ay around.  The 
ce90: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51  SQLITE_IOCAP_SEQ
cea0: 55 45 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79  UENTIAL property
ceb0: 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69   means that.** i
cec0: 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72  nformation is wr
ced0: 69 74 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e  itten to disk in
cee0: 20 74 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20   the same order 
cef0: 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78  as calls.** to x
cf00: 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49  Write()..**.** I
cf10: 66 20 78 52 65 61 64 28 29 20 72 65 74 75 72 6e  f xRead() return
cf20: 73 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53  s SQLITE_IOERR_S
cf30: 48 4f 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73  HORT_READ it mus
cf40: 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69  t also fill.** i
cf50: 6e 20 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72  n the unread por
cf60: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66  tions of the buf
cf70: 66 65 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20  fer with zeros. 
cf80: 20 41 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66   A VFS that.** f
cf90: 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  ails to zero-fil
cfa0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69  l short reads mi
cfb0: 67 68 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b  ght seem to work
cfc0: 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
cfd0: 61 69 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66  ailure to zero-f
cfe0: 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20  ill short reads 
cff0: 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20  will eventually 
d000: 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62  lead to.** datab
d010: 61 73 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  ase corruption..
d020: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
d030: 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  t sqlite3_io_met
d040: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f  hods sqlite3_io_
d050: 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20  methods;.struct 
d060: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
d070: 64 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  ds {.  int iVers
d080: 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c  ion;.  int (*xCl
d090: 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ose)(sqlite3_fil
d0a0: 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  e*);.  int (*xRe
d0b0: 61 64 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ad)(sqlite3_file
d0c0: 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41  *, void*, int iA
d0d0: 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  mt, sqlite3_int6
d0e0: 34 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20  4 iOfst);.  int 
d0f0: 28 2a 78 57 72 69 74 65 29 28 73 71 6c 69 74 65  (*xWrite)(sqlite
d100: 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76  3_file*, const v
d110: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
d120: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
d130: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54  fst);.  int (*xT
d140: 72 75 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33  runcate)(sqlite3
d150: 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f  _file*, sqlite3_
d160: 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69  int64 size);.  i
d170: 6e 74 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69  nt (*xSync)(sqli
d180: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66  te3_file*, int f
d190: 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78  lags);.  int (*x
d1a0: 46 69 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65  FileSize)(sqlite
d1b0: 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33  3_file*, sqlite3
d1c0: 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a  _int64 *pSize);.
d1d0: 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73    int (*xLock)(s
d1e0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
d1f0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c  t);.  int (*xUnl
d200: 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ock)(sqlite3_fil
d210: 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20  e*, int);.  int 
d220: 28 2a 78 43 68 65 63 6b 52 65 73 65 72 76 65 64  (*xCheckReserved
d230: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
d240: 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  le*, int *pResOu
d250: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c  t);.  int (*xFil
d260: 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65  eControl)(sqlite
d270: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c  3_file*, int op,
d280: 20 76 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20   void *pArg);.  
d290: 69 6e 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a  int (*xSectorSiz
d2a0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
d2b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69  );.  int (*xDevi
d2c0: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
d2d0: 73 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  s)(sqlite3_file*
d2e0: 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20  );.  /* Methods 
d2f0: 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20  above are valid 
d300: 66 6f 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f  for version 1 */
d310: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70  .  int (*xShmMap
d320: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
d330: 20 69 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67   int iPg, int pg
d340: 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f  sz, int, void vo
d350: 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74  latile**);.  int
d360: 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c   (*xShmLock)(sql
d370: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
d380: 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69  offset, int n, i
d390: 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69  nt flags);.  voi
d3a0: 64 20 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29  d (*xShmBarrier)
d3b0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
d3c0: 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d  .  int (*xShmUnm
d3d0: 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ap)(sqlite3_file
d3e0: 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61  *, int deleteFla
d3f0: 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73  g);.  /* Methods
d400: 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64   above are valid
d410: 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a   for version 2 *
d420: 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61  /.  /* Additiona
d430: 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65  l methods may be
d440: 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65   added in future
d450: 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a   releases */.};.
d460: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d470: 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43   Standard File C
d480: 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a  ontrol Opcodes.*
d490: 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67  *.** These integ
d4a0: 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  er constants are
d4b0: 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65   opcodes for the
d4c0: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
d4d0: 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  thod.** of the [
d4e0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
d4f0: 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66  ds] object and f
d500: 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  or the [sqlite3_
d510: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a  file_control()].
d520: 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  ** interface..**
d530: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
d540: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d  FCNTL_LOCKSTATE]
d550: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
d560: 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20  for debugging.  
d570: 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63  This.** opcode c
d580: 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65 43  auses the xFileC
d590: 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f  ontrol method to
d5a0: 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72 65   write the curre
d5b0: 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74  nt state of.** t
d5c0: 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20  he lock (one of 
d5d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e  [SQLITE_LOCK_NON
d5e0: 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  E], [SQLITE_LOCK
d5f0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51  _SHARED],.** [SQ
d600: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
d610: 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  ED], [SQLITE_LOC
d620: 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b  K_PENDING], or [
d630: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
d640: 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20  USIVE]).** into 
d650: 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  an integer that 
d660: 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  the pArg argumen
d670: 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69  t points to. Thi
d680: 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20  s capability.** 
d690: 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  is used during t
d6a0: 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20  esting and only 
d6b0: 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70 70  needs to be supp
d6c0: 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54  orted when SQLIT
d6d0: 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66  E_TEST.** is def
d6e0: 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ined..** <ul>.**
d6f0: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
d700: 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a  NTL_SIZE_HINT]].
d710: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
d720: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 20  CNTL_SIZE_HINT] 
d730: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 62  opcode is used b
d740: 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76 65  y SQLite to give
d750: 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79 65   the VFS.** laye
d760: 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77 20  r a hint of how 
d770: 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62 61  large the databa
d780: 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72 6f  se file will gro
d790: 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20 74  w to be during t
d7a0: 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74 72  he.** current tr
d7b0: 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69 73  ansaction.  This
d7c0: 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75 61   hint is not gua
d7d0: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61 63  ranteed to be ac
d7e0: 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a 2a  curate but it.**
d7f0: 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65 2e   is often close.
d800: 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67    The underlying
d810: 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f 73   VFS might choos
d820: 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74 65  e to preallocate
d830: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
d840: 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f 6e  e space based on
d850: 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f 72   this hint in or
d860: 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69 74  der to help writ
d870: 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  es to the databa
d880: 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20 66  se.** file run f
d890: 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  aster..**.** <li
d8a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
d8b0: 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20  CHUNK_SIZE]].** 
d8c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
d8d0: 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70  L_CHUNK_SIZE] op
d8e0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
d8f0: 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68 65  request that the
d900: 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73 20   VFS.** extends 
d910: 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74 68  and truncates th
d920: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
d930: 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20 73  in chunks of a s
d940: 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ize specified.**
d950: 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54 68   by the user. Th
d960: 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
d970: 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 69  t to [sqlite3_fi
d980: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73 68  le_control()] sh
d990: 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20 74  ould .** point t
d9a0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74 79  o an integer (ty
d9b0: 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e 69  pe int) containi
d9c0: 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e 6b  ng the new chunk
d9d0: 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a 20  -size to use.** 
d9e0: 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74 65  for the nominate
d9f0: 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c 6f  d database. Allo
da00: 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65 20  cating database 
da10: 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c 61  file space in la
da20: 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28 73  rge.** chunks (s
da30: 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d 65  ay 1MB at a time
da40: 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66 69  ), may reduce fi
da50: 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d 65  le-system fragme
da60: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69  ntation and.** i
da70: 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
da80: 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74 65  ce on some syste
da90: 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ms..**.** <li>[[
daa0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
dab0: 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54  E_POINTER]].** T
dac0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
dad0: 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f  _FILE_POINTER] o
dae0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
daf0: 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65   obtain a pointe
db00: 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  r.** to the [sql
db10: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
db20: 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  t associated wit
db30: 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64  h a particular d
db40: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
db50: 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20  ction.  See the 
db60: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
db70: 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e  ntrol()] documen
db80: 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64  tation for.** ad
db90: 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
dba0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  tion..**.** <li>
dbb0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53  [[SQLITE_FCNTL_S
dbc0: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a  YNC_OMITTED]].**
dbd0: 20 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46   ^(The [SQLITE_F
dbe0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
dbf0: 44 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e  D] opcode is gen
dc00: 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c  erated internall
dc10: 79 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61  y by.** SQLite a
dc20: 6e 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56  nd sent to all V
dc30: 46 53 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66  FSes in place of
dc40: 20 61 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78   a call to the x
dc50: 53 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77  Sync method.** w
dc60: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
dc70: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20   connection has 
dc80: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
dc90: 6f 75 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e  ous] set to OFF.
dca0: 29 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69  )^.** Some speci
dcb0: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65  alized VFSes nee
dcc0: 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e  d this signal in
dcd0: 20 6f 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74   order to operat
dce0: 65 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77  e correctly.** w
dcf0: 68 65 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63  hen [PRAGMA sync
dd00: 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41  hronous | PRAGMA
dd10: 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46   synchronous=OFF
dd20: 5d 20 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f  ] is set, but mo
dd30: 73 74 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20  st .** VFSes do 
dd40: 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69  not need this si
dd50: 67 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20  gnal and should 
dd60: 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20  silently ignore 
dd70: 74 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20  this opcode..** 
dd80: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  Applications sho
dd90: 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71  uld not call [sq
dda0: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
ddb0: 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a  ol()] with this.
ddc0: 2a 2a 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  ** opcode as doi
ddd0: 6e 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70  ng so may disrup
dde0: 74 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  t the operation 
ddf0: 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a  of the specializ
de00: 65 64 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74  ed VFSes.** that
de10: 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20   do require it. 
de20: 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51   .**.** <li>[[SQ
de30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
de40: 5f 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e  _AV_RETRY]].** ^
de50: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
de60: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
de70: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
de80: 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75   to configure au
de90: 74 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79  tomatic.** retry
dea0: 20 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65   counts and inte
deb0: 72 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69  rvals for certai
dec0: 6e 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61  n disk I/O opera
ded0: 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a  tions for the.**
dee0: 20 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69   windows [VFS] i
def0: 6e 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69  n order to provi
df00: 64 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e  de robustness in
df10: 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   the presence of
df20: 0a 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70  .** anti-virus p
df30: 72 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66  rograms.  By def
df40: 61 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77  ault, the window
df50: 73 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79  s VFS will retry
df60: 20 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66   file read,.** f
df70: 69 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66  ile write, and f
df80: 69 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61  ile delete opera
df90: 74 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74  tions up to 10 t
dfa0: 69 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c  imes, with a del
dfb0: 61 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c  ay.** of 25 mill
dfc0: 69 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20  iseconds before 
dfd0: 74 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20  the first retry 
dfe0: 61 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c  and with the del
dff0: 61 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a  ay increasing.**
e000: 20 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61   by an additiona
e010: 6c 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  l 25 millisecond
e020: 73 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73  s with each subs
e030: 65 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54  equent retry.  T
e040: 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c  his.** opcode al
e050: 6c 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76  lows these two v
e060: 61 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65  alues (10 retrie
e070: 73 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65  s and 25 millise
e080: 63 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a  conds of delay).
e090: 2a 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65  ** to be adjuste
e0a0: 64 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61  d.  The values a
e0b0: 72 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61  re changed for a
e0c0: 6c 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ll database conn
e0d0: 65 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69  ections.** withi
e0e0: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
e0f0: 73 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  ss.  The argumen
e100: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
e110: 6f 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77  o an array of tw
e120: 6f 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68  o.** integers wh
e130: 65 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e  ere the first in
e140: 74 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20  teger i the new 
e150: 72 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20  retry count and 
e160: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e  the second.** in
e170: 74 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c  teger is the del
e180: 61 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69  ay.  If either i
e190: 6e 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69  nteger is negati
e1a0: 76 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74  ve, then the set
e1b0: 74 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  ting.** is not c
e1c0: 68 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65  hanged but inste
e1d0: 61 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c  ad the prior val
e1e0: 75 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69  ue of that setti
e1f0: 6e 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a  ng is written.**
e200: 20 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20   into the array 
e210: 65 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20  entry, allowing 
e220: 74 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72  the current retr
e230: 79 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65  y settings to be
e240: 0a 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64  .** interrogated
e250: 2e 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70  .  The zDbName p
e260: 61 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f  arameter is igno
e270: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  red..**.** <li>[
e280: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
e290: 52 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e  RSIST_WAL]].** ^
e2a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
e2b0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f  L_PERSIST_WAL] o
e2c0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
e2d0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
e2e0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
e2f0: 5b 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65  [WAL | Write Ahe
e300: 61 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e  ad Log] setting.
e310: 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68    By default, th
e320: 65 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77  e auxiliary.** w
e330: 72 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61  rite ahead log a
e340: 6e 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79  nd shared memory
e350: 20 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20   files used for 
e360: 74 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  transaction cont
e370: 72 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d  rol.** are autom
e380: 61 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64  atically deleted
e390: 20 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74   when the latest
e3a0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74   connection to t
e3b0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
e3c0: 6c 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20  loses.  Setting 
e3d0: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
e3e0: 6f 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65  ode causes those
e3f0: 20 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73   files to persis
e400: 74 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65  t after.** close
e410: 2e 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68  .  Persisting th
e420: 65 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75  e files is usefu
e430: 6c 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f  l when other pro
e440: 63 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e  cesses that do n
e450: 6f 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65  ot.** have write
e460: 20 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74   permission on t
e470: 68 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e  he directory con
e480: 74 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61  taining the data
e490: 62 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a  base file want.*
e4a0: 2a 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61  * to read the da
e4b0: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20  tabase file, as 
e4c0: 74 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72  the WAL and shar
e4d0: 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20  ed memory files 
e4e0: 6d 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e  must exist.** in
e4f0: 20 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64   order for the d
e500: 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
e510: 61 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75  adable.  The fou
e520: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
e530: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
e540: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
e550: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
e560: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
e570: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
e580: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
e590: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
e5a0: 70 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d  persistent WAL m
e5b0: 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62  ode or 1 to enab
e5c0: 6c 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a  le persistent.**
e5d0: 20 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74   WAL mode.  If t
e5e0: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
e5f0: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
e600: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
e610: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c  e current.** WAL
e620: 20 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74   persistence set
e630: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
e640: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  [[SQLITE_FCNTL_P
e650: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
e660: 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  TE]].** ^The [SQ
e670: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
e680: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
e690: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
e6a0: 6f 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74  o set or query t
e6b0: 68 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74  he.** persistent
e6c0: 20 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72   "powersafe-over
e6d0: 77 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22  write" or "PSOW"
e6e0: 20 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50   setting.  The P
e6f0: 53 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64  SOW setting.** d
e700: 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53  etermines the [S
e710: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45  QLITE_IOCAP_POWE
e720: 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d  RSAFE_OVERWRITE]
e730: 20 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78   bit of the.** x
e740: 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69  DeviceCharacteri
e750: 73 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54  stics methods. T
e760: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
e770: 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
e780: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
e790: 29 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f  )] for this opco
e7a0: 64 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70  de should be a p
e7b0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74  ointer to an int
e7c0: 65 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e  eger..** That in
e7d0: 74 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69  teger is 0 to di
e7e0: 73 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  sable zero-damag
e7f0: 65 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65  e mode or 1 to e
e800: 6e 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67  nable zero-damag
e810: 65 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74  e.** mode.  If t
e820: 68 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31  he integer is -1
e830: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65  , then it is ove
e840: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
e850: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72  e current.** zer
e860: 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65  o-damage mode se
e870: 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tting..**.** <li
e880: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
e890: 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e  OVERWRITE]].** ^
e8a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
e8b0: 4c 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63  L_OVERWRITE] opc
e8c0: 6f 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62  ode is invoked b
e8d0: 79 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f  y SQLite after o
e8e0: 70 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74  pening.** a writ
e8f0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f  e transaction to
e900: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20   indicate that, 
e910: 75 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c  unless it is rol
e920: 6c 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d  led back for som
e930: 65 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65  e.** reason, the
e940: 20 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65   entire database
e950: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76   file will be ov
e960: 65 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65  erwritten by the
e970: 20 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61   current .** tra
e980: 6e 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69  nsaction. This i
e990: 73 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d  s used by VACUUM
e9a0: 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a   operations..**.
e9b0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
e9c0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a  FCNTL_VFSNAME]].
e9d0: 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  ** ^The [SQLITE_
e9e0: 46 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f  FCNTL_VFSNAME] o
e9f0: 70 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65  pcode can be use
ea00: 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20  d to obtain the 
ea10: 6e 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20  names of.** all 
ea20: 5b 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56  [VFSes] in the V
ea30: 46 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e  FS stack.  The n
ea40: 61 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20  ames are of all 
ea50: 56 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68  VFS shims and th
ea60: 65 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f  e.** final botto
ea70: 6d 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20  m-level VFS are 
ea80: 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d  written into mem
ea90: 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
eaa0: 6d 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  m .** [sqlite3_m
eab0: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65  alloc()] and the
eac0: 20 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65   result is store
ead0: 64 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76  d in the char* v
eae0: 61 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20  ariable.** that 
eaf0: 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
eb00: 65 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33  eter of [sqlite3
eb10: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
eb20: 20 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54   points to..** T
eb30: 68 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73  he caller is res
eb40: 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65  ponsible for fre
eb50: 65 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20  eing the memory 
eb60: 77 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77  when done.  As w
eb70: 69 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d  ith.** all file-
eb80: 63 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c  control actions,
eb90: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61   there is no gua
eba0: 72 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73  rantee that this
ebb0: 20 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a   will actually.*
ebc0: 2a 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20  * do anything.  
ebd0: 43 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69  Callers should i
ebe0: 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68  nitialize the ch
ebf0: 61 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20  ar* variable to 
ec00: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
ec10: 72 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66  r in case this f
ec20: 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e  ile-control is n
ec30: 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20  ot implemented. 
ec40: 20 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   This file-contr
ec50: 6f 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65  ol.** is intende
ec60: 64 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63  d for diagnostic
ec70: 20 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a   use only..**.**
ec80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
ec90: 4e 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20  NTL_PRAGMA]].** 
eca0: 5e 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41  ^Whenever a [PRA
ecb0: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  GMA] statement i
ecc0: 73 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51  s parsed, an [SQ
ecd0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
ece0: 41 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  A] .** file cont
ecf0: 72 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74  rol is sent to t
ed00: 68 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33  he open [sqlite3
ed10: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f  _file] object co
ed20: 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74  rresponding.** t
ed30: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
ed40: 69 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65  ile to which the
ed50: 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e   pragma statemen
ed60: 74 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61  t refers. ^The a
ed70: 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68  rgument.** to th
ed80: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
ed90: 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e  PRAGMA] file con
eda0: 74 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79  trol is an array
edb0: 20 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20   of.** pointers 
edc0: 74 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72  to strings (char
edd0: 2a 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65  **) in which the
ede0: 20 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20   second element 
edf0: 6f 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20  of the array.** 
ee00: 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
ee10: 68 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68  he pragma and th
ee20: 65 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20  e third element 
ee30: 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  is the argument 
ee40: 74 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61  to the.** pragma
ee50: 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20   or NULL if the 
ee60: 70 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72  pragma has no ar
ee70: 67 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61  gument.  ^The ha
ee80: 6e 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20  ndler for an.** 
ee90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
eea0: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
eeb0: 6f 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c  ol can optionall
eec0: 79 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74  y make the first
eed0: 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74   element.** of t
eee0: 68 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65  he char** argume
eef0: 6e 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  nt point to a st
ef00: 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72  ring obtained fr
ef10: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69  om [sqlite3_mpri
ef20: 6e 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65  ntf()].** or the
ef30: 20 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20   equivalent and 
ef40: 74 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c  that string will
ef50: 20 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75   become the resu
ef60: 6c 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61  lt of the pragma
ef70: 20 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72   or.** the error
ef80: 20 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20   message if the 
ef90: 70 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49  pragma fails. ^I
efa0: 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
efb0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66  _FCNTL_PRAGMA] f
efc0: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75  ile control retu
efd0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46  rns [SQLITE_NOTF
efe0: 4f 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d  OUND], then norm
eff0: 61 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20  al .** [PRAGMA] 
f000: 70 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69  processing conti
f010: 6e 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b  nues.  ^If the [
f020: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
f030: 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e  GMA].** file con
f040: 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51  trol returns [SQ
f050: 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74  LITE_OK], then t
f060: 68 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65  he parser assume
f070: 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46  s that the.** VF
f080: 53 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68  S has handled th
f090: 65 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20  e PRAGMA itself 
f0a0: 61 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67  and the parser g
f0b0: 65 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70  enerates a no-op
f0c0: 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61  .** prepared sta
f0d0: 74 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65  tement.  ^If the
f0e0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
f0f0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
f100: 72 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  rol returns.** a
f110: 6e 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f  ny result code o
f120: 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
f130: 45 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45  E_OK] or [SQLITE
f140: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74  _NOTFOUND], that
f150: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74   means.** that t
f160: 68 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72  he VFS encounter
f170: 65 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c  ed an error whil
f180: 65 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b  e handling the [
f190: 50 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a  PRAGMA] and the.
f1a0: 2a 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f  ** compilation o
f1b0: 66 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69  f the PRAGMA fai
f1c0: 6c 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  ls with an error
f1d0: 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f  .  ^The [SQLITE_
f1e0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a  FCNTL_PRAGMA].**
f1f0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63   file control oc
f200: 63 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69  curs at the begi
f210: 6e 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20  nning of pragma 
f220: 73 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73  statement analys
f230: 69 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20  is and so.** it 
f240: 69 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72  is able to overr
f250: 69 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52  ide built-in [PR
f260: 41 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73  AGMA] statements
f270: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
f280: 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48  LITE_FCNTL_BUSYH
f290: 41 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 69  ANDLER]].** ^Thi
f2a0: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d  s file-control m
f2b0: 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 62 79  ay be invoked by
f2c0: 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65 20 64   SQLite on the d
f2d0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61 6e  atabase file han
f2e0: 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79 20 61  dle.** shortly a
f2f0: 66 74 65 72 20 69 74 20 69 73 20 6f 70 65 6e 65  fter it is opene
f300: 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 70 72  d in order to pr
f310: 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d 20 56  ovide a custom V
f320: 46 53 20 77 69 74 68 20 61 63 63 65 73 73 0a 2a  FS with access.*
f330: 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65 63 74  * to the connect
f340: 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64 6c 65  ions busy-handle
f350: 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68 65 20  r callback. The 
f360: 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66 20 74  argument is of t
f370: 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a  ype (void **).**
f380: 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74   - an array of t
f390: 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61 6c 75  wo (void *) valu
f3a0: 65 73 2e 20 54 68 65 20 66 69 72 73 74 20 28 76  es. The first (v
f3b0: 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c 79 20  oid *) actually 
f3c0: 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61 20 66  points.** to a f
f3d0: 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20  unction of type 
f3e0: 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20 2a 29  (int (*)(void *)
f3f0: 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 69  ). In order to i
f400: 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e 65 63  nvoke the connec
f410: 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d 68 61  tions.** busy-ha
f420: 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75 6e 63  ndler, this func
f430: 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65 20 69  tion should be i
f440: 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68 65 20  nvoked with the 
f450: 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a 29 20  second (void *) 
f460: 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61 79 20  in.** the array 
f470: 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72 67 75  as the only argu
f480: 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65 74 75  ment. If it retu
f490: 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68  rns non-zero, th
f4a0: 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  en the operation
f4b0: 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
f4c0: 74 72 69 65 64 2e 20 49 66 20 69 74 20 72 65 74  tried. If it ret
f4d0: 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65 20 63  urns zero, the c
f4e0: 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75 6c 64  ustom VFS should
f4f0: 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20   abandon the.** 
f500: 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74 69 6f  current operatio
f510: 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  n..**.** <li>[[S
f520: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
f530: 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41  FILENAME]].** ^A
f540: 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 69  pplication can i
f550: 6e 76 6f 6b 65 20 74 68 69 73 20 66 69 6c 65 2d  nvoke this file-
f560: 63 6f 6e 74 72 6f 6c 20 74 6f 20 68 61 76 65 20  control to have 
f570: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
f580: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
f590: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
f5a0: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
f5b0: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
f5c0: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
f5d0: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
f5e0: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
f5f0: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
f600: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
f610: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
f620: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
f630: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
f640: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
f650: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
f660: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
f670: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
f680: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
f690: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
f6a0: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
f6b0: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
f6c0: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
f6d0: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
f6e0: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c  leak..**.** </ul
f6f0: 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
f700: 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54  ITE_FCNTL_LOCKST
f710: 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
f720: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
f730: 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_GET_LOCKPROXY
f740: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
f750: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
f760: 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46  E_SET_LOCKPROXYF
f770: 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ILE             
f780: 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
f790: 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20 20  _LAST_ERRNO     
f7a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 34                 4
f7b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
f7c0: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
f7d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
f7e0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
f7f0: 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 20  CNTL_CHUNK_SIZE 
f800: 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
f810: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
f820: 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52  NTL_FILE_POINTER
f830: 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64              7.#d
f840: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
f850: 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20  TL_SYNC_OMITTED 
f860: 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64 65             8.#de
f870: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
f880: 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59  L_WIN32_AV_RETRY
f890: 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66            9.#def
f8a0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
f8b0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20 20  _PERSIST_WAL    
f8c0: 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66 69          10.#defi
f8d0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
f8e0: 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20 20  OVERWRITE       
f8f0: 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69 6e         11.#defin
f900: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 56  e SQLITE_FCNTL_V
f910: 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20 20  FSNAME          
f920: 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e 65        12.#define
f930: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f   SQLITE_FCNTL_PO
f940: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
f950: 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65 20  E    13.#define 
f960: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
f970: 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20 20  GMA             
f980: 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20 53      14.#define S
f990: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59  QLITE_FCNTL_BUSY
f9a0: 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20 20  HANDLER         
f9b0: 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53 51     15.#define SQ
f9c0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46  LITE_FCNTL_TEMPF
f9d0: 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20 20  ILENAME         
f9e0: 20 20 31 36 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    16../*.** CAPI
f9f0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
fa00: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
fa10: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
fa20: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
fa30: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
fa40: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
fa50: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
fa60: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
fa70: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
fa80: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
fa90: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
faa0: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
fab0: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
fac0: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
fad0: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
fae0: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
faf0: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
fb00: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
fb10: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
fb20: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
fb30: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
fb40: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
fb50: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
fb60: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
fb70: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
fb80: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
fb90: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
fba0: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
fbb0: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
fbc0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
fbd0: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
fbe0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
fbf0: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
fc00: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
fc10: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
fc20: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
fc30: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
fc40: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
fc50: 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65  le system".  See
fc60: 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56  .** the [VFS | V
fc70: 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  FS documentation
fc80: 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e  ] for further in
fc90: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
fca0: 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   The value of th
fcb0: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
fcc0: 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20   is initially 1 
fcd0: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
fce0: 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76  r in.** future v
fcf0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
fd00: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
fd10: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
fd20: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
fd30: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
fd40: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
fd50: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e  is increased.  N
fd60: 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72  ote that the str
fd70: 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65  ucture.** of the
fd80: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
fd90: 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74  ect changes in t
fda0: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
fdb0: 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  etween.** SQLite
fdc0: 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61   version 3.5.9 a
fdd0: 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74  nd 3.6.0 and yet
fde0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
fdf0: 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d  eld was not.** m
fe00: 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  odified..**.** T
fe10: 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c  he szOsFile fiel
fe20: 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  d is the size of
fe30: 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20   the subclassed 
fe40: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a  [sqlite3_file].*
fe50: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64  * structure used
fe60: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d   by this VFS.  m
fe70: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65  xPathname is the
fe80: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
fe90: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65  of.** a pathname
fea0: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a   in this VFS..**
feb0: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73  .** Registered s
fec0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
fed0: 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61  ts are kept on a
fee0: 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72   linked list for
fef0: 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e  med by.** the pN
ff00: 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ext pointer.  Th
ff10: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  e [sqlite3_vfs_r
ff20: 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e  egister()].** an
ff30: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  d [sqlite3_vfs_u
ff40: 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74  nregister()] int
ff50: 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74  erfaces manage t
ff60: 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61  his list.** in a
ff70: 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79   thread-safe way
ff80: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
ff90: 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65  vfs_find()] inte
ffa0: 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65  rface.** searche
ffb0: 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69  s the list.  Nei
ffc0: 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  ther the applica
ffd0: 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68  tion code nor th
ffe0: 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65  e VFS.** impleme
fff0: 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  ntation should u
10000 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  se the pNext poi
10010 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
10020 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74  pNext field is t
10030 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e  he only field in
10040 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
10050 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68  .** structure th
10060 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  at SQLite will e
10070 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c  ver modify.  SQL
10080 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63  ite will only ac
10090 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66  cess.** or modif
100a0 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69  y this field whi
100b0 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
100c0 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
100d0 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
100e0 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
100f0 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
10100 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65  thing within the
10110 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
10120 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20  object once the 
10130 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20  object has been 
10140 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a  registered..**.*
10150 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
10160 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
10170 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
10180 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
10190 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
101a0 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
101b0 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  odules..**.** [[
101c0 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
101d0 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  n]].** ^SQLite g
101e0 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
101f0 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
10200 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
10210 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
10220 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
10230 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
10240 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
10250 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
10260 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
10270 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
10280 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
10290 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
102a0 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
102b0 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
102c0 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
102d0 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
102e0 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
102f0 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65  .** 11 alphanume
10300 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
10310 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
10320 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
10330 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
10340 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
10350 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
10360 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
10370 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
10380 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
10390 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
103a0 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
103b0 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
103c0 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
103d0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
103e0 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
103f0 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
10400 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
10410 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
10420 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
10430 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
10440 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
10450 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
10460 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
10470 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
10480 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
10490 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
104a0 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
104b0 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
104c0 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
104d0 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
104e0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
104f0 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
10500 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
10510 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
10520 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
10530 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
10540 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
10550 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
10560 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
10570 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
10580 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
10590 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
105a0 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
105b0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
105c0 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
105d0 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
105e0 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
105f0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
10600 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
10610 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
10620 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
10630 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
10640 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
10650 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
10660 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
10670 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
10680 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
10690 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
106a0 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
106b0 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
106c0 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
106d0 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
106e0 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
106f0 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
10700 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
10710 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
10720 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
10730 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
10740 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
10750 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
10760 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
10770 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
10780 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
10790 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
107a0 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
107b0 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
107c0 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
107d0 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
107e0 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
107f0 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
10800 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
10810 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
10820 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
10830 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
10840 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
10850 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
10860 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
10870 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
10880 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
10890 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
108a0 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
108b0 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
108c0 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
108d0 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
108e0 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
108f0 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
10900 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
10910 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
10920 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
10930 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
10940 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
10950 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
10960 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
10970 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
10980 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
10990 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
109a0 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
109b0 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
109c0 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
109d0 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
109e0 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
109f0 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
10a00 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
10a10 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
10a20 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
10a30 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
10a40 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
10a50 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
10a60 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
10a70 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
10a80 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
10a90 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
10aa0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
10ab0 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
10ac0 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
10ad0 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
10ae0 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
10af0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
10b00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
10b10 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
10b20 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
10b30 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
10b40 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
10b50 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
10b60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
10b70 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
10b80 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
10b90 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
10ba0 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
10bb0 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
10bc0 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
10bd0 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
10be0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
10bf0 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
10c00 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
10c10 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
10c20 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
10c30 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
10c40 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
10c50 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
10c60 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
10c70 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
10c80 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
10c90 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
10ca0 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
10cb0 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
10cc0 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
10cd0 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
10ce0 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
10cf0 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
10d00 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
10d10 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
10d20 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
10d30 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
10d40 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
10d50 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
10d60 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
10d70 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
10d80 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
10d90 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
10da0 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
10db0 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
10dc0 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
10dd0 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
10de0 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
10df0 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
10e00 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
10e10 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
10e20 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
10e30 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
10e40 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
10e50 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
10e60 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
10e70 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
10e80 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
10e90 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
10ea0 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
10eb0 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
10ec0 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
10ed0 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
10ee0 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
10ef0 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
10f00 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
10f10 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
10f20 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
10f30 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
10f40 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
10f50 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
10f60 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
10f70 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
10f80 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
10f90 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
10fa0 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
10fb0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
10fc0 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
10fd0 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
10fe0 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
10ff0 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41  [[sqlite3_vfs.xA
11000 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20  ccess]].** ^The 
11010 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
11020 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
11030 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
11040 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
11050 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
11060 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
11070 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
11080 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
11090 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
110a0 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
110b0 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
110c0 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
110d0 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
110e0 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
110f0 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
11100 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
11110 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
11120 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
11130 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
11140 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
11150 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
11160 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
11170 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
11180 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
11190 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
111a0 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
111b0 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
111c0 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
111d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
111e0 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
111f0 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
11200 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
11210 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
11220 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
11230 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
11240 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
11250 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
11260 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
11270 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
11280 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
11290 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
112a0 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
112b0 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
112c0 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
112d0 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
112e0 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
112f0 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
11300 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  ), xCurrentTime(
11310 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
11320 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e  imeInt64().** in
11330 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74  terfaces are not
11340 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74   strictly a part
11350 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74   of the filesyst
11360 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65  em, but they are
11370 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  .** included in 
11380 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72  the VFS structur
11390 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65  e for completene
113a0 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ss..** The xRand
113b0 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f  omness() functio
113c0 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  n attempts to re
113d0 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65  turn nBytes byte
113e0 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61  s.** of good-qua
113f0 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20  lity randomness 
11400 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
11410 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a  return value is.
11420 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75  ** the actual nu
11430 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
11440 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
11450 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c  ined..** The xSl
11460 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
11470 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ses the calling 
11480 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20  thread to sleep 
11490 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20  for at.** least 
114a0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
114b0 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e  croseconds given
114c0 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  .  ^The xCurrent
114d0 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
114e0 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
114f0 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
11500 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
11510 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a  e and time as.**
11520 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
11530 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65  t value..** ^The
11540 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
11550 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  64() method retu
11560 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67  rns, as an integ
11570 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a  er, the Julian.*
11580 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c  * Day Number mul
11590 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30  tiplied by 86400
115a0 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20  000 (the number 
115b0 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
115c0 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72  in .** a 24-hour
115d0 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c   day).  .** ^SQL
115e0 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
115f0 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
11600 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67  64() method to g
11610 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  et the current.*
11620 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  * date and time 
11630 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69  if that method i
11640 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20  s available (if 
11650 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72  iVersion is 2 or
11660 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64   .** greater and
11670 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
11680 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
11690 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c  L) and will fall
116a0 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72   back.** to xCur
116b0 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43  rentTime() if xC
116c0 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
116d0 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  ) is unavailable
116e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65  ..**.** ^The xSe
116f0 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78  tSystemCall(), x
11700 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  GetSystemCall(),
11710 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d   and xNestSystem
11720 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  Call() interface
11730 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65  s.** are not use
11740 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20  d by the SQLite 
11750 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74  core.  These opt
11760 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ional interfaces
11770 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a   are provided.**
11780 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74   by some VFSes t
11790 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73  o facilitate tes
117a0 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20  ting of the VFS 
117b0 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64  code. By overrid
117c0 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63  ing .** system c
117d0 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69  alls with functi
117e0 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f  ons under its co
117f0 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72  ntrol, a test pr
11800 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d  ogram can.** sim
11810 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64  ulate faults and
11820 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e   error condition
11830 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68  s that would oth
11840 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63  erwise be diffic
11850 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73  ult.** or imposs
11860 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20  ible to induce. 
11870 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74   The set of syst
11880 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61  em calls that ca
11890 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a  n be overridden.
118a0 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f  ** varies from o
118b0 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65  ne VFS to anothe
118c0 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20  r, and from one 
118d0 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73  version of the s
118e0 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a  ame VFS to the.*
118f0 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
11900 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74  tions that use t
11910 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
11920 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64  must be prepared
11930 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61   for any.** or a
11940 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ll of these inte
11950 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c  rfaces to be NUL
11960 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62  L or for their b
11970 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67  ehavior to chang
11980 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65  e.** from one re
11990 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78  lease to the nex
119a0 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
119b0 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70   must not attemp
119c0 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61  t to access.** a
119d0 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68  ny of these meth
119e0 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73  ods if the iVers
119f0 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69  ion of the VFS i
11a00 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a  s less than 3..*
11a10 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
11a20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
11a30 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65  ite3_vfs;.typede
11a40 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
11a50 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f  _syscall_ptr)(vo
11a60 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  id);.struct sqli
11a70 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
11a80 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
11a90 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
11aa0 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
11ab0 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a   (currently 3) *
11ac0 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
11ad0 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
11ae0 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
11af0 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
11b00 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
11b10 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
11b20 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
11b30 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
11b40 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
11b50 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
11b60 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
11b70 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
11b80 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
11b90 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
11ba0 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
11bb0 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
11bc0 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
11bd0 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
11be0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
11bf0 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
11c00 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
11c10 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
11c20 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
11c30 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
11c40 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
11c50 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
11c60 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
11c70 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
11c80 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
11c90 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
11ca0 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
11cb0 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
11cc0 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
11cd0 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
11ce0 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
11cf0 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
11d00 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
11d10 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
11d20 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
11d30 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
11d40 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
11d50 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
11d60 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
11d70 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
11d80 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
11d90 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
11da0 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
11db0 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28  rrMsg);.  void (
11dc0 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
11dd0 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
11de0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
11df0 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f  ol))(void);.  vo
11e00 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
11e10 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
11e20 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
11e30 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
11e40 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
11e50 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
11e60 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
11e70 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
11e80 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
11e90 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
11ea0 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
11eb0 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
11ec0 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
11ed0 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
11ee0 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
11ef0 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
11f00 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
11f10 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f  e in version 1 o
11f20 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
11f30 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66   object.  ** def
11f40 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20  inition.  Those 
11f50 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20  that follow are 
11f60 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e  added in version
11f70 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f   2 or later.  */
11f80 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
11f90 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69  tTimeInt64)(sqli
11fa0 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65  te3_vfs*, sqlite
11fb0 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a  3_int64*);.  /*.
11fc0 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
11fd0 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
11fe0 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f  rsions 1 and 2 o
11ff0 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
12000 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68   object..  ** Th
12010 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f  ose below are fo
12020 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20  r version 3 and 
12030 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20  greater..  */.  
12040 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d  int (*xSetSystem
12050 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
12060 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
12070 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
12080 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73  yscall_ptr);.  s
12090 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
120a0 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43  tr (*xGetSystemC
120b0 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
120c0 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
120d0 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63  Name);.  const c
120e0 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74  har *(*xNextSyst
120f0 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
12100 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
12110 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20   *zName);.  /*. 
12120 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
12130 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
12140 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20  sions 1 through 
12150 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  3 of the sqlite_
12160 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
12170 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
12180 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
12190 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
121a0 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
121b0 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
121c0 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
121d0 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a   this happens. .
121e0 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43    */.};../*.** C
121f0 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
12200 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
12210 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
12220 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
12230 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
12240 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
12250 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
12260 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
12270 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
12280 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
12290 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
122a0 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
122b0 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
122c0 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
122d0 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
122e0 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
122f0 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
12300 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
12310 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
12320 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
12330 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
12340 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
12350 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
12360 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
12370 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
12380 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74  the named direct
12390 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64  ory is both read
123a0 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
123b0 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77  e.** (in other w
123c0 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63  ords, if files c
123d0 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d  an be added, rem
123e0 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65  oved, and rename
123f0 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
12400 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54  directory)..** T
12410 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
12420 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74  _READWRITE const
12430 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ant is currently
12440 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68   used only by th
12450 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65  e.** [temp_store
12460 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
12470 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20  a], though this 
12480 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20  could change in 
12490 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
124a0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
124b0 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
124c0 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
124d0 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
124e0 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
124f0 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
12500 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54  able.  The SQLIT
12510 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f  E_ACCESS_READ co
12520 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72  nstant is.** cur
12530 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74  rently unused, t
12540 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62  hough it might b
12550 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75  e used in a futu
12560 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
12570 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
12580 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
12590 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
125a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
125b0 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20  ESS_READWRITE 1 
125c0 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41    /* Used by PRA
125d0 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64  GMA temp_store_d
125e0 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66  irectory */.#def
125f0 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
12600 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20  S_READ      2   
12610 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a  /* Unused */../*
12620 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
12630 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d  ags for the xShm
12640 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a  Lock VFS method.
12650 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
12660 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ger constants de
12670 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73  fine the various
12680 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69   locking operati
12690 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62  ons.** allowed b
126a0 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  y the xShmLock m
126b0 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65  ethod of [sqlite
126c0 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20  3_io_methods].  
126d0 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  The.** following
126e0 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65   are the only le
126f0 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  gal combinations
12700 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65   of flags to the
12710 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  .** xShmLock met
12720 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
12730 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
12740 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
12750 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
12760 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
12770 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
12780 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
12790 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
127a0 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
127b0 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
127c0 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
127d0 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
127e0 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
127f0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65   </ul>.**.** Whe
12800 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65  n unlocking, the
12810 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20   same SHARED or 
12820 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d  EXCLUSIVE flag m
12830 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20  ust be supplied 
12840 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20  as.** was given 
12850 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  no the correspon
12860 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a  ding lock.  .**.
12870 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
12880 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73  method can trans
12890 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e  ition between un
128a0 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45  locked and SHARE
128b0 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20  D or.** between 
128c0 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43  unlocked and EXC
128d0 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e  LUSIVE.  It cann
128e0 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  ot transition be
128f0 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20  tween SHARED.** 
12900 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a  and EXCLUSIVE..*
12910 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12920 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  _SHM_UNLOCK     
12930 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
12940 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20  TE_SHM_LOCK     
12950 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
12960 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20  LITE_SHM_SHARED 
12970 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
12980 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
12990 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a  SIVE    8../*.**
129a0 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d   CAPI3REF: Maxim
129b0 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65  um xShmLock inde
129c0 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d  x.**.** The xShm
129d0 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b  Lock method on [
129e0 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
129f0 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75  ds] may use valu
12a00 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  es.** between 0 
12a10 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62  and this upper b
12a20 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66  ound as its "off
12a30 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  set" argument..*
12a40 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
12a50 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74  e will never att
12a60 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20  empt to acquire 
12a70 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20  or release a.** 
12a80 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20  lock outside of 
12a90 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64  this range.*/.#d
12aa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
12ab0 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a  _NLOCK        8.
12ac0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
12ad0 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
12ae0 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
12af0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
12b00 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
12b10 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69  routine initiali
12b20 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74  zes the.** SQLit
12b30 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65  e library.  ^The
12b40 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
12b50 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
12b60 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
12b70 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
12b80 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
12b90 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
12ba0 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ze()..** These r
12bb0 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69  outines are desi
12bc0 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70  gned to aid in p
12bd0 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
12be0 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75  ation and.** shu
12bf0 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65  tdown on embedde
12c00 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b  d systems.  Work
12c10 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74  station applicat
12c20 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ions using.** SQ
12c30 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f  Lite normally do
12c40 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76   not need to inv
12c50 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68  oke either of th
12c60 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
12c70 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
12c80 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
12c90 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
12ca0 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
12cb0 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
12cc0 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
12cd0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
12ce0 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
12cf0 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
12d00 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
12d10 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
12d20 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
12d30 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
12d40 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
12d50 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
12d60 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12d70 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66  .  ^(Only an eff
12d80 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
12d90 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
12da0 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
12db0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
12dc0 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
12dd0 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
12de0 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
12df0 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
12e00 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73  e3_shutdown() is
12e10 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
12e20 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68  call if it is th
12e30 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20  e first.** call 
12e40 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
12e50 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20  own() since the 
12e60 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  last sqlite3_ini
12e70 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e  tialize().  ^(On
12e80 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69  ly.** an effecti
12e90 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ve call to sqlit
12ea0 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f  e3_shutdown() do
12eb0 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c  es any deinitial
12ec0 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20  ization..** All 
12ed0 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c  other valid call
12ee0 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  s to sqlite3_shu
12ef0 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d  tdown() are harm
12f00 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
12f10 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
12f20 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e  _initialize() in
12f30 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61  terface is threa
12f40 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74  dsafe, but sqlit
12f50 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
12f60 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71   is not.  The sq
12f70 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
12f80 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20   interface must 
12f90 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66  only be called f
12fa0 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20  rom a.** single 
12fb0 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65  thread.  All ope
12fc0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
12fd0 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65  ections] must be
12fe0 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a   closed and all.
12ff0 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ** other SQLite 
13000 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62  resources must b
13010 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72  e deallocated pr
13020 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a  ior to invoking.
13030 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ** sqlite3_shutd
13040 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  own()..**.** Amo
13050 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
13060 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   ^sqlite3_initia
13070 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f  lize() will invo
13080 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
13090 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
130a0 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68  rly, ^sqlite3_sh
130b0 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c  utdown().** will
130c0 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
130d0 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
130e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
130f0 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
13100 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
13110 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
13120 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d  ..** ^If for som
13130 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65  e reason, sqlite
13140 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
13150 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74  s unable to init
13160 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69  ialize.** the li
13170 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69  brary (perhaps i
13180 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  t is unable to a
13190 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64  llocate a needed
131a0 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a   resource such.*
131b0 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74  * as a mutex) it
131c0 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72   returns an [err
131d0 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74  or code] other t
131e0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  han [SQLITE_OK].
131f0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
13200 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
13210 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
13220 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
13230 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
13240 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
13250 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
13260 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
13270 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
13280 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
13290 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
132a0 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
132b0 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
132c0 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
132d0 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
132e0 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
132f0 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
13300 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
13310 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
13320 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
13330 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
13340 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
13350 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
13360 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77  * already.  ^How
13370 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
13380 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13390 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   the [SQLITE_OMI
133a0 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63  T_AUTOINIT].** c
133b0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
133c0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
133d0 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
133e0 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
133f0 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
13400 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
13410 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
13420 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
13430 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
13440 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
13450 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
13460 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
13470 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
13480 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
13490 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
134a0 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
134b0 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
134c0 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
134d0 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
134e0 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
134f0 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
13500 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
13510 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
13520 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
13530 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
13540 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
13550 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
13560 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
13570 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13580 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
13590 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65  TOINIT] might be
135a0 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
135b0 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
135c0 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
135d0 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
135e0 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
135f0 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
13600 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
13610 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
13620 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
13630 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
13640 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
13650 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
13660 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
13670 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
13680 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
13690 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
136a0 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
136b0 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
136c0 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
136d0 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
136e0 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
136f0 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
13700 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
13710 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
13720 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
13730 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
13740 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
13750 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
13760 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
13770 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
13780 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
13790 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
137a0 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
137b0 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
137c0 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
137d0 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
137e0 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
137f0 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
13800 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
13810 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
13820 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
13830 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
13840 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
13850 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
13860 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
13870 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
13880 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
13890 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
138a0 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
138b0 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
138c0 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
138d0 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
138e0 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
138f0 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
13900 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
13910 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
13920 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
13930 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
13940 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
13950 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73  or Unix, Windows
13960 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68  , or OS/2..** Wh
13970 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64  en [custom build
13980 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  s | built for ot
13990 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a  her platforms].*
139a0 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51  * (using the [SQ
139b0 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d  LITE_OS_OTHER=1]
139c0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
139d0 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
139e0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
139f0 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
13a00 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
13a10 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
13a20 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
13a30 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
13a40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
13a50 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
13a60 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
13a70 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
13a80 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
13a90 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
13aa0 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
13ab0 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65  success and some
13ac0 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f   other [error co
13ad0 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c  de] upon.** fail
13ae0 75 72 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ure..*/.SQLITE_A
13af0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  PI int sqlite3_i
13b00 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
13b10 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
13b20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
13b30 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41  (void);.SQLITE_A
13b40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  PI int sqlite3_o
13b50 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 53 51  s_init(void);.SQ
13b60 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
13b70 69 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64  ite3_os_end(void
13b80 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
13b90 45 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20  EF: Configuring 
13ba0 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61  The SQLite Libra
13bb0 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ry.**.** The sql
13bc0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e  ite3_config() in
13bd0 74 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20  terface is used 
13be0 74 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63  to make global c
13bf0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20  onfiguration.** 
13c00 63 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74  changes to SQLit
13c10 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75  e in order to tu
13c20 6e 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65  ne SQLite to the
13c30 20 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20   specific needs 
13c40 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
13c50 61 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61  ation.  The defa
13c60 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ult configuratio
13c70 6e 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  n is recommended
13c80 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70   for most.** app
13c90 6c 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f  lications and so
13ca0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73   this routine is
13cb0 20 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63   usually not nec
13cc0 65 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a  essary.  It is.*
13cd0 2a 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75  * provided to su
13ce0 70 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69  pport rare appli
13cf0 63 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75  cations with unu
13d00 73 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a  sual needs..**.*
13d10 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f  * The sqlite3_co
13d20 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65  nfig() interface
13d30 20 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61   is not threadsa
13d40 66 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61  fe.  The applica
13d50 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73  tion.** must ins
13d60 75 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65  ure that no othe
13d70 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
13d80 63 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20  ces are invoked 
13d90 62 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65  by other.** thre
13da0 61 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65  ads while sqlite
13db0 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75  3_config() is ru
13dc0 6e 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d  nning.  Furtherm
13dd0 6f 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e  ore, sqlite3_con
13de0 66 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  fig().** may onl
13df0 79 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69  y be invoked pri
13e00 6f 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e  or to library in
13e10 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69  itialization usi
13e20 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69  ng.** [sqlite3_i
13e30 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20  nitialize()] or 
13e40 61 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62  after shutdown b
13e50 79 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64  y [sqlite3_shutd
13e60 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73  own()]..** ^If s
13e70 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
13e80 69 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20  is called after 
13e90 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
13ea0 69 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72  ize()] and befor
13eb0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  e.** [sqlite3_sh
13ec0 75 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69  utdown()] then i
13ed0 74 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51  t will return SQ
13ee0 4c 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20  LITE_MISUSE..** 
13ef0 4e 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74  Note, however, t
13f00 68 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e  hat ^sqlite3_con
13f10 66 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c  fig() can be cal
13f20 6c 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74  led as part of t
13f30 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
13f40 74 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69  tion of an appli
13f50 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b  cation-defined [
13f60 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
13f70 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  )]..**.** The fi
13f80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  rst argument to 
13f90 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
13fa0 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a   is an integer.*
13fb0 2a 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  * [configuration
13fc0 20 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65   option] that de
13fd0 74 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74  termines.** what
13fe0 20 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c   property of SQL
13ff0 69 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e  ite is to be con
14000 66 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71  figured.  Subseq
14010 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a  uent arguments.*
14020 2a 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67  * vary depending
14030 20 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75   on the [configu
14040 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a  ration option].*
14050 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
14060 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
14070 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61  When a configura
14080 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73  tion option is s
14090 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  et, sqlite3_conf
140a0 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51  ig() returns [SQ
140b0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66  LITE_OK]..** ^If
140c0 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75   the option is u
140d0 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65  nknown or SQLite
140e0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65   is unable to se
140f0 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20  t the option.** 
14100 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e  then this routin
14110 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d  e returns a non-
14120 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65  zero [error code
14130 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  ]..*/.SQLITE_API
14140 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e   int sqlite3_con
14150 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
14160 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
14170 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
14180 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
14190 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
141a0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
141b0 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
141c0 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
141d0 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
141e0 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
141f0 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
14200 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
14210 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
14220 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
14230 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
14240 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
14250 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
14260 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
14270 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
14280 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
14290 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
142a0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
142b0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
142c0 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
142d0 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
142e0 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
142f0 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
14300 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
14310 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
14320 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
14330 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
14340 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
14350 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
14360 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
14370 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
14380 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
14390 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
143a0 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
143b0 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
143c0 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
143d0 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
143e0 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
143f0 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
14400 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
14410 65 73 73 66 75 6c 2e 0a 2a 2f 0a 53 51 4c 49 54  essful..*/.SQLIT
14420 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
14430 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69  3_db_config(sqli
14440 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e  te3*, int op, ..
14450 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
14460 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f  REF: Memory Allo
14470 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a  cation Routines.
14480 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
14490 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
144a0 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
144b0 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 20 53  erface between S
144c0 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77  QLite.** and low
144d0 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c  -level memory al
144e0 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
144f0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62  s..**.** This ob
14500 6a 65 63 74 20 69 73 20 75 73 65 64 20 69 6e 20  ject is used in 
14510 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69  only one place i
14520 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74  n the SQLite int
14530 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69  erface..** A poi
14540 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
14550 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
14560 63 74 20 69 73 20 74 68 65 20 61 72 67 75 6d 65  ct is the argume
14570 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  nt to.** [sqlite
14580 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e  3_config()] when
14590 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
145a0 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20  on option is.** 
145b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
145c0 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54  ALLOC] or [SQLIT
145d0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
145e0 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65  OC].  .** By cre
145f0 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63  ating an instanc
14600 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
14610 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20  .** and passing 
14620 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  it to [sqlite3_c
14630 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
14640 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a  ONFIG_MALLOC]).*
14650 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75  * during configu
14660 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69  ration, an appli
14670 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69  cation can speci
14680 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
14690 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
146a0 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d  cation subsystem
146b0 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75   for SQLite to u
146c0 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74  se for all of it
146d0 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d  s.** dynamic mem
146e0 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ory needs..**.**
146f0 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74   Note that SQLit
14700 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76  e comes with sev
14710 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d  eral [built-in m
14720 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
14730 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65  ].** that are pe
14740 72 66 65 63 74 6c 79 20 61 64 65 71 75 61 74 65  rfectly adequate
14750 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65   for the overwhe
14760 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f  lming majority o
14770 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a  f applications.*
14780 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20  * and that this 
14790 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75  object is only u
147a0 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20  seful to a tiny 
147b0 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c  minority of appl
147c0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68  ications.** with
147d0 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d   specialized mem
147e0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
147f0 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68  equirements.  Th
14800 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20  is object is.** 
14810 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67  also used during
14820 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69   testing of SQLi
14830 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73  te in order to s
14840 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e  pecify an altern
14850 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  ative.** memory 
14860 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73  allocator that s
14870 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20  imulates memory 
14880 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f  out-of-memory co
14890 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f  nditions in.** o
148a0 72 64 65 72 20 74 6f 20 76 65 72 69 66 79 20 74  rder to verify t
148b0 68 61 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76  hat SQLite recov
148c0 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66  ers gracefully f
148d0 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64  rom such.** cond
148e0 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  itions..**.** Th
148f0 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c  e xMalloc, xReal
14900 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d  loc, and xFree m
14910 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b  ethods must work
14920 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c   like the.** mal
14930 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29  loc(), realloc()
14940 20 61 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63   and free() func
14950 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73  tions from the s
14960 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72  tandard C librar
14970 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75  y..** ^SQLite gu
14980 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
14990 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
149a0 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63  t to.** xRealloc
149b0 20 69 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c   is always a val
149c0 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 61  ue returned by a
149d0 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78   prior call to x
149e0 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78  Roundup..**.** x
149f0 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75  Size should retu
14a00 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64  rn the allocated
14a10 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72   size of a memor
14a20 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
14a30 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69  previously obtai
14a40 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63  ned from xMalloc
14a50 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54   or xRealloc.  T
14a60 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a  he allocated siz
14a70 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61  e.** is always a
14a80 74 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61  t least as big a
14a90 73 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20  s the requested 
14aa0 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20  size but may be 
14ab0 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68  larger..**.** Th
14ac0 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f  e xRoundup metho
14ad0 64 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77  d returns what w
14ae0 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f  ould be the allo
14af0 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a  cated size of.**
14b00 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61   a memory alloca
14b10 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72  tion given a par
14b20 74 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65  ticular requeste
14b30 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65  d size.  Most me
14b40 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f  mory.** allocato
14b50 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f  rs round up memo
14b60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61  ry allocations a
14b70 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e  t least to the n
14b80 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20  ext multiple.** 
14b90 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f  of 8.  Some allo
14ba0 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20  cators round up 
14bb0 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74  to a larger mult
14bc0 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77  iple or to a pow
14bd0 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72  er of 2..** Ever
14be0 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  y memory allocat
14bf0 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69  ion request comi
14c00 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73  ng in through [s
14c10 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
14c20 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
14c30 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74  realloc()] first
14c40 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e   calls xRoundup.
14c50 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65    If xRoundup re
14c60 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61  turns 0, .** tha
14c70 74 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72  t causes the cor
14c80 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72  responding memor
14c90 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20  y allocation to 
14ca0 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fail..**.** The 
14cb0 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69  xInit method ini
14cc0 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d  tializes the mem
14cd0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
14ce0 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a  (For example,.**
14cf0 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61   it might alloca
14d00 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d  te any require m
14d10 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61  utexes or initia
14d20 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61  lize internal da
14d30 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73  ta.** structures
14d40 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e  .  The xShutdown
14d50 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
14d60 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20  ed (indirectly) 
14d70 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  by.** [sqlite3_s
14d80 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73  hutdown()] and s
14d90 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65  hould deallocate
14da0 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61   any resources a
14db0 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49  cquired.** by xI
14dc0 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61  nit.  The pAppDa
14dd0 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73  ta pointer is us
14de0 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70  ed as the only p
14df0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78  arameter to.** x
14e00 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f  Init and xShutdo
14e10 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  wn..**.** SQLite
14e20 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49   holds the [SQLI
14e30 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f  TE_MUTEX_STATIC_
14e40 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68  MASTER] mutex wh
14e50 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a  en it invokes.**
14e60 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   the xInit metho
14e70 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20  d, so the xInit 
14e80 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20  method need not 
14e90 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  be threadsafe.  
14ea0 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e  The.** xShutdown
14eb0 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20   method is only 
14ec0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c  called from [sql
14ed0 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d  ite3_shutdown()]
14ee0 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e   so it does.** n
14ef0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68  ot need to be th
14f00 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e  readsafe either.
14f10 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20    For all other 
14f20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a  methods, SQLite.
14f30 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51  ** holds the [SQ
14f40 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49  LITE_MUTEX_STATI
14f50 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20  C_MEM] mutex as 
14f60 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b  long as the.** [
14f70 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
14f80 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75  MSTATUS] configu
14f90 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
14fa0 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63   turned on (whic
14fb0 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65  h.** it is by de
14fc0 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68  fault) and so th
14fd0 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75  e methods are au
14fe0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69  tomatically seri
14ff0 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76  alized..** Howev
15000 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  er, if [SQLITE_C
15010 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
15020 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68   is disabled, th
15030 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20  en the other.** 
15040 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20  methods must be 
15050 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c  threadsafe or el
15060 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77  se make their ow
15070 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66  n arrangements f
15080 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74  or.** serializat
15090 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ion..**.** SQLit
150a0 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76  e will never inv
150b0 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65  oke xInit() more
150c0 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f   than once witho
150d0 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e  ut an intervenin
150e0 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68  g.** call to xSh
150f0 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70  utdown()..*/.typ
15100 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
15110 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
15120 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
15130 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
15140 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20  te3_mem_methods 
15150 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c  {.  void *(*xMal
15160 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20  loc)(int);      
15170 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c     /* Memory all
15180 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  ocation function
15190 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72   */.  void (*xFr
151a0 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20  ee)(void*);     
151b0 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70       /* Free a p
151c0 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
151d0 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65  */.  void *(*xRe
151e0 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74  alloc)(void*,int
151f0 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e  );  /* Resize an
15200 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
15210 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f   int (*xSize)(vo
15220 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
15230 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69  /* Return the si
15240 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74  ze of an allocat
15250 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
15260 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20  Roundup)(int);  
15270 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64          /* Round
15280 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65   up request size
15290 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73   to allocation s
152a0 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ize */.  int (*x
152b0 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20  Init)(void*);   
152c0 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69          /* Initi
152d0 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79  alize the memory
152e0 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20   allocator */.  
152f0 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e  void (*xShutdown
15300 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f  )(void*);      /
15310 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74  * Deinitialize t
15320 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
15330 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70  tor */.  void *p
15340 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20  AppData;        
15350 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d          /* Argum
15360 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61  ent to xInit() a
15370 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a  nd xShutdown() *
15380 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.};../*.** CAPI
15390 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74  3REF: Configurat
153a0 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b  ion Options.** K
153b0 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67  EYWORDS: {config
153c0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a  uration option}.
153d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
153e0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
153f0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
15400 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
15410 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
15420 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
15430 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
15440 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  t to the [sqlite
15450 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
15460 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
15470 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15480 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
15490 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
154a0 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
154b0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
154c0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
154d0 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
154e0 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
154f0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
15500 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
15510 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
15520 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
15530 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
15540 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77  at.** the call w
15550 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c  orked.  The [sql
15560 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69  ite3_config()] i
15570 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
15580 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
15590 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
155a0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
155b0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
155c0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
155d0 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
155e0 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
155f0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
15600 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d  IG_SINGLETHREAD]
15610 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
15620 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
15630 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
15640 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
15650 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
15660 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
15670 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
15680 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
15690 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e  o Single-thread.
156a0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
156b0 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
156c0 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e   all mutexing an
156d0 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e  d puts SQLite in
156e0 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20  to a mode where 
156f0 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75  it can only be u
15700 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67  sed.** by a sing
15710 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66  le thread.   ^If
15720 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
15730 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
15740 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
15750 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
15760 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
15770 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
15780 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
15790 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e  possible to chan
157a0 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ge the [threadin
157b0 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73  g mode] from its
157c0 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75   default.** valu
157d0 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65  e of Single-thre
157e0 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74  ad and so [sqlit
157f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c  e3_config()] wil
15800 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51  l return .** [SQ
15810 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63  LITE_ERROR] if c
15820 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53  alled with the S
15830 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e  QLITE_CONFIG_SIN
15840 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e  GLETHREAD.** con
15850 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15860 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
15870 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
15880 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e  LTITHREAD]] <dt>
15890 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
158a0 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a  LTITHREAD</dt>.*
158b0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
158c0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
158d0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
158e0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
158f0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
15900 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69  g mode] to Multi
15910 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
15920 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
15930 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e  ables.** mutexin
15940 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63  g on [database c
15950 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b  onnection] and [
15960 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
15970 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20  nt] objects..** 
15980 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
15990 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
159a0 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61  or serializing a
159b0 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74  ccess to.** [dat
159c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
159d0 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  s] and [prepared
159e0 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42   statements].  B
159f0 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73  ut other mutexes
15a00 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20  .** are enabled 
15a10 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  so that SQLite w
15a20 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75  ill be safe to u
15a30 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68  se in a multi-th
15a40 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f  readed.** enviro
15a50 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73  nment as long as
15a60 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20   no two threads 
15a70 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74  attempt to use t
15a80 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61  he same.** [data
15a90 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
15aa0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
15ab0 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  e.  ^If SQLite i
15ac0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
15ad0 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
15ae0 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
15af0 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
15b00 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
15b10 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20  tion then.** it 
15b20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20  is not possible 
15b30 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69  to set the Multi
15b40 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
15b50 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20  ng mode] and.** 
15b60 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
15b70 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  )] will return [
15b80 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66  SQLITE_ERROR] if
15b90 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65   called with the
15ba0 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  .** SQLITE_CONFI
15bb0 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f  G_MULTITHREAD co
15bc0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15bd0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
15be0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
15bf0 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e  ERIALIZED]] <dt>
15c00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
15c10 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a  RIALIZED</dt>.**
15c20 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
15c30 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
15c40 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
15c50 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
15c60 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
15c70 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c   mode] to Serial
15c80 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77  ized. In other w
15c90 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f  ords, this optio
15ca0 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c  n enables.** all
15cb0 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69   mutexes includi
15cc0 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65  ng the recursive
15cd0 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b  .** mutexes on [
15ce0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
15cf0 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72  ion] and [prepar
15d00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62  ed statement] ob
15d10 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69  jects..** In thi
15d20 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73  s mode (which is
15d30 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65   the default whe
15d40 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  n SQLite is comp
15d50 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51  iled with.** [SQ
15d60 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
15d70 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c  1]) the SQLite l
15d80 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65  ibrary will itse
15d90 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63  lf serialize acc
15da0 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62  ess.** to [datab
15db0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d  ase connections]
15dc0 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73   and [prepared s
15dd0 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68  tatements] so th
15de0 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63  at the.** applic
15df0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f  ation is free to
15e00 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64   use the same [d
15e10 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
15e20 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61  on] or the.** sa
15e30 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  me [prepared sta
15e40 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65  tement] in diffe
15e50 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20  rent threads at 
15e60 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a  the same time..*
15e70 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  * ^If SQLite is 
15e80 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
15e90 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
15ea0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
15eb0 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
15ec0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
15ed0 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
15ee0 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
15ef0 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69   set the Seriali
15f00 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  zed [threading m
15f10 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ode] and.** [sql
15f20 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
15f30 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
15f40 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c  TE_ERROR] if cal
15f50 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
15f60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
15f70 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75  RIALIZED configu
15f80 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f  ration option.</
15f90 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
15fa0 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
15fb0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
15fc0 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  NFIG_MALLOC</dt>
15fd0 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
15fe0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
15ff0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
16000 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
16010 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
16020 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
16030 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
16040 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
16050 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
16060 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
16070 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d  ve low-level mem
16080 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72  ory allocation r
16090 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73  outines to be us
160a0 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  ed in place of.*
160b0 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  * the memory all
160c0 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
160d0 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
160e0 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61  te.)^ ^SQLite ma
160f0 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70  kes.** its own p
16100 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
16110 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
16120 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
16130 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
16140 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20  e.** before the 
16150 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
16160 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  )] call returns.
16170 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
16180 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
16190 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
161a0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c  TE_CONFIG_GETMAL
161b0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
161c0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
161d0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
161e0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
161f0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
16200 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
16210 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
16220 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
16230 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  re.  The [sqlite
16240 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a  3_mem_methods].*
16250 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
16260 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
16270 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
16280 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
16290 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a  on routines.)^.*
162a0 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61  * This option ca
162b0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65  n be used to ove
162c0 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c  rload the defaul
162d0 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  t memory allocat
162e0 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
162f0 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74  with a wrapper t
16300 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20  hat simulations 
16310 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
16320 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20  n failure or.** 
16330 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73  tracks memory us
16340 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  age, for example
16350 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  . </dd>.**.** [[
16360 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
16370 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51  MSTATUS]] <dt>SQ
16380 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53  LITE_CONFIG_MEMS
16390 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  TATUS</dt>.** <d
163a0 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
163b0 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67  takes single arg
163c0 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
163d0 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  t, interpreted a
163e0 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c  s a .** boolean,
163f0 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f   which enables o
16400 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63  r disables the c
16410 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d  ollection of mem
16420 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a  ory allocation .
16430 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e  ** statistics. ^
16440 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  (When memory all
16450 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
16460 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c  cs are disabled,
16470 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69   the .** followi
16480 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ng SQLite interf
16490 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d  aces become non-
164a0 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20  operational:.** 
164b0 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e    <ul>.**   <li>
164c0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
164d0 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c  _used()].**   <l
164e0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  i> [sqlite3_memo
164f0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a  ry_highwater()].
16500 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
16510 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
16520 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  it64()].**   <li
16530 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75  > [sqlite3_statu
16540 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29  s()].**   </ul>)
16550 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c  ^.** ^Memory all
16560 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69  ocation statisti
16570 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62  cs are enabled b
16580 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73  y default unless
16590 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f   SQLite is.** co
165a0 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
165b0 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
165c0 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63  TATUS]=0 in whic
165d0 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a  h case memory.**
165e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74   allocation stat
165f0 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62  istics are disab
16600 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a  led by default..
16610 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ** </dd>.**.** [
16620 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
16630 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c  CRATCH]] <dt>SQL
16640 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
16650 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
16660 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
16670 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
16680 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
16690 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
166a0 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
166b0 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
166c0 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
166d0 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
166e0 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
166f0 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
16700 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
16710 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
16720 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
16730 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
16740 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
16750 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
16760 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
16770 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
16780 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
16790 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
167a0 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
167b0 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
167c0 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72  f 16..** The fir
167d0 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
167e0 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
167f0 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
16800 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
16810 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
16820 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
16830 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
16840 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
16850 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66  two scratch buff
16860 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20  ers per thread. 
16870 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
16880 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20  be set to twice 
16890 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
168a0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
168b0 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69  hreads..** ^SQLi
168c0 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
168d0 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
168e0 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
168f0 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
16900 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
16910 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
16920 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
16930 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
16940 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
16950 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
16960 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
16970 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
16980 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
16990 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
169a0 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
169b0 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
169c0 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
169d0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
169e0 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45  CONFIG_PAGECACHE
169f0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
16a00 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f  NFIG_PAGECACHE</
16a10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
16a20 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
16a30 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
16a40 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
16a50 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f  QLite can use fo
16a60 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  r.** the databas
16a70 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74  e page cache wit
16a80 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61  h the default pa
16a90 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
16aa0 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68  ntation.  .** Th
16ab0 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  is configuration
16ac0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
16ad0 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63  sed if an applic
16ae0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67  ation-define pag
16af0 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65  e.** cache imple
16b00 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61  mentation is loa
16b10 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53 51  ded using the SQ
16b20 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
16b30 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54  HE2 option..** T
16b40 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
16b50 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
16b60 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74   option: A point
16b70 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c 69  er to 8-byte ali
16b80 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  gned.** memory, 
16b90 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
16ba0 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73 7a   page buffer (sz
16bb0 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62 65  ), and the numbe
16bc0 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e 0a  r of pages (N)..
16bd0 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d 65  ** The sz argume
16be0 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68 65  nt should be the
16bf0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61 72   size of the lar
16c00 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70 61  gest database pa
16c10 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f  ge.** (a power o
16c20 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35 31  f two between 51
16c30 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c 75  2 and 32768) plu
16c40 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72 61  s a little extra
16c50 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61 67   for each.** pag
16c60 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65 20  e header.  ^The 
16c70 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a 65  page header size
16c80 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79 74   is 20 to 40 byt
16c90 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a  es depending on.
16ca0 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63 68  ** the host arch
16cb0 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20 69  itecture.  ^It i
16cc0 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61 72  s harmless, apar
16cd0 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74 65  t from the waste
16ce0 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20  d memory,.** to 
16cf0 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c 65  make sz a little
16d00 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68 65   too large.  The
16d10 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65   first.** argume
16d20 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
16d30 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  to an allocation
16d40 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a 2a   of at least sz*
16d50 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72  N bytes of memor
16d60 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69  y..** ^SQLite wi
16d70 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f 72  ll use the memor
16d80 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74 68  y provided by th
16d90 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
16da0 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73 0a   to satisfy its.
16db0 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20  ** memory needs 
16dc0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e 20  for the first N 
16dd0 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61 64  pages that it ad
16de0 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e 49  ds to cache.  ^I
16df0 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  f additional.** 
16e00 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72  page cache memor
16e10 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79 6f  y is needed beyo
16e20 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76 69  nd what is provi
16e30 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74 69  ded by this opti
16e40 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  on, then.** SQLi
16e50 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69  te goes to [sqli
16e60 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f  te3_malloc()] fo
16e70 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61 6c  r the additional
16e80 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e 0a   storage space..
16e90 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20 69  ** The pointer i
16ea0 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
16eb0 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20  ment must.** be 
16ec0 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d  aligned to an 8-
16ed0 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f 72  byte boundary or
16ee0 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68 61   subsequent beha
16ef0 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a  vior of SQLite.*
16f00 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69  * will be undefi
16f10 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ned.</dd>.**.** 
16f20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
16f30 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  HEAP]] <dt>SQLIT
16f40 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64  E_CONFIG_HEAP</d
16f50 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
16f60 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
16f70 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
16f80 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
16f90 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
16fa0 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 20   for all of its 
16fb0 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61  dynamic memory a
16fc0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 20  llocation needs 
16fd0 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f  beyond those pro
16fe0 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20  vided.** for by 
16ff0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  [SQLITE_CONFIG_S
17000 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c  CRATCH] and [SQL
17010 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43  ITE_CONFIG_PAGEC
17020 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  ACHE]..** There 
17030 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
17040 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20 61  nts: An 8-byte a
17050 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20 74  ligned pointer t
17060 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a  o the memory,.**
17070 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
17080 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f  ytes in the memo
17090 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20 74  ry buffer, and t
170a0 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
170b0 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e  ation size..** ^
170c0 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f 69  If the first poi
170d0 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72 79  nter (the memory
170e0 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55 4c   pointer) is NUL
170f0 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 72  L, then SQLite r
17100 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69  everts.** to usi
17110 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20 6d  ng its default m
17120 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
17130 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c  (the system mall
17140 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74  oc() implementat
17150 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67  ion),.** undoing
17160 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f 63   any prior invoc
17170 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45  ation of [SQLITE
17180 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e  _CONFIG_MALLOC].
17190 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d    ^If the.** mem
171a0 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20 6e  ory pointer is n
171b0 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68  ot NULL and eith
171c0 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  er [SQLITE_ENABL
171d0 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a  E_MEMSYS3] or.**
171e0 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
171f0 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65 66  MEMSYS5] are def
17200 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20 61  ined, then the a
17210 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72  lternative memor
17220 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69  y.** allocator i
17230 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61 6e  s engaged to han
17240 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74  dle all of SQLit
17250 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  es memory alloca
17260 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54  tion needs..** T
17270 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72  he first pointer
17280 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69   (the memory poi
17290 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61 6c  nter) must be al
172a0 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79  igned to an 8-by
172b0 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f  te.** boundary o
172c0 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
172d0 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 20  avior of SQLite 
172e0 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65  will be undefine
172f0 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75  d..** The minimu
17300 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  m allocation siz
17310 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20 32  e is capped at 2
17320 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65  **12. Reasonable
17330 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74   values.** for t
17340 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63  he minimum alloc
17350 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20 32  ation size are 2
17360 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a 38  **5 through 2**8
17370 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
17380 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54  QLITE_CONFIG_MUT
17390 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  EX]] <dt>SQLITE_
173a0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
173b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
173c0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
173d0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
173e0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
173f0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
17400 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
17410 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
17420 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
17430 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
17440 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
17450 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
17460 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
17470 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
17480 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
17490 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
174a0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
174b0 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
174c0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
174d0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
174e0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
174f0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
17500 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
17510 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
17520 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
17530 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
17540 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
17550 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
17560 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
17570 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
17580 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
17590 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
175a0 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
175b0 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
175c0 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
175d0 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
175e0 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
175f0 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
17600 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
17610 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
17620 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
17630 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
17640 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
17650 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
17660 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 5d  CONFIG_GETMUTEX]
17670 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
17680 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74  FIG_GETMUTEX</dt
17690 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
176a0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
176b0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
176c0 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
176d0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
176e0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
176f0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
17700 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
17710 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
17720 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a  mutex_methods].*
17730 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66  * structure is f
17740 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63  illed with the c
17750 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64  urrently defined
17760 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 2e   mutex routines.
17770 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f  )^.** This optio
17780 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  n can be used to
17790 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64 65   overload the de
177a0 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f  fault mutex allo
177b0 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e  cation.** routin
177c0 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70 65  es with a wrappe
177d0 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b 20  r used to track 
177e0 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72 20  mutex usage for 
177f0 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70  performance.** p
17800 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73 74  rofiling or test
17810 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65  ing, for example
17820 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69  .   ^If SQLite i
17830 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a  s compiled with.
17840 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  ** the [SQLITE_T
17850 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49  HREADSAFE | SQLI
17860 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
17870 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
17880 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65  tion then.** the
17890 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67   entire mutexing
178a0 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d   subsystem is om
178b0 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62  itted from the b
178c0 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63  uild and hence c
178d0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
178e0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
178f0 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
17900 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63 6f  NFIG_GETMUTEX co
17910 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
17920 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72  on will.** retur
17930 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  n [SQLITE_ERROR]
17940 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
17950 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
17960 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c  KASIDE]] <dt>SQL
17970 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
17980 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  SIDE</dt>.** <dd
17990 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
179a0 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65  takes two argume
179b0 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69  nts that determi
179c0 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a 2a  ne the default.*
179d0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
179e0 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b  ion for the look
179f0 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  aside memory all
17a00 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a  ocator on each.*
17a10 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
17a20 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69  ection].  The fi
17a30 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
17a40 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
17a50 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
17a60 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74 68  ffer slot and th
17a70 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65 20  e second is the 
17a80 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f  number of.** slo
17a90 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20  ts allocated to 
17aa0 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63 6f  each database co
17ab0 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54  nnection.)^  ^(T
17ac0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
17ad0 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c  the.** <i>defaul
17ae0 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20  t</i> lookaside 
17af0 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49 54  size. The [SQLIT
17b00 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
17b10 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f  SIDE].** verb to
17b20 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
17b30 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75 73  fig()] can be us
17b40 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  ed to change the
17b50 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f   lookaside.** co
17b60 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69  nfiguration on i
17b70 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63  ndividual connec
17b80 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a  tions.)^ </dd>.*
17b90 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
17ba0 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c  NFIG_PCACHE2]] <
17bb0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
17bc0 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a  _PCACHE2</dt>.**
17bd0 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
17be0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
17bf0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
17c00 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
17c10 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33  o.** an [sqlite3
17c20 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
17c30 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73 20  ] object.  This 
17c40 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65 73  object specifies
17c50 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a   the interface.*
17c60 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70 61  * to a custom pa
17c70 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ge cache impleme
17c80 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c  ntation.)^  ^SQL
17c90 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
17ca0 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63   of the.** objec
17cb0 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66 6f  t and uses it fo
17cc0 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  r page cache mem
17cd0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e  ory allocations.
17ce0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
17cf0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
17d00 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c  CACHE2]] <dt>SQL
17d10 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
17d20 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
17d30 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
17d40 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
17d50 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
17d60 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
17d70 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63  n.** [sqlite3_pc
17d80 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
17d90 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63  bject.  SQLite c
17da0 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75 72  opies of the cur
17db0 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63  rent.** page cac
17dc0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
17dd0 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65  n into that obje
17de0 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ct.)^ </dd>.**.*
17df0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
17e00 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49  G_LOG]] <dt>SQLI
17e10 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64  TE_CONFIG_LOG</d
17e20 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 65 20  t>.** <dd> ^The 
17e30 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
17e40 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
17e50 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
17e60 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
17e70 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
17e80 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
17e90 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
17ea0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
17eb0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
17ec0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
17ed0 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
17ee0 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
17ef0 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
17f00 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
17f10 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
17f20 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
17f30 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
17f40 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
17f50 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
17f60 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
17f70 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
17f80 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
17f90 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
17fa0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
17fb0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
17fc0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
17fd0 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
17fe0 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
17ff0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
18000 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
18010 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
18020 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
18030 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
18040 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
18050 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
18060 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
18070 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
18080 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
18090 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
180a0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
180b0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
180c0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
180d0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
180e0 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
180f0 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
18100 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
18110 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
18120 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
18130 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
18140 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
18150 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
18160 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
18170 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
18180 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
18190 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
181a0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
181b0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
181c0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
181d0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
181e0 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
181f0 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
18200 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
18210 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
18220 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
18230 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
18240 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
18250 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
18260 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
18270 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
18280 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
18290 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
182a0 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73 20 6f  I.** <dd> This o
182b0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
182c0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
182d0 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e 6f   type int. If no
182e0 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a 20  n-zero, then.** 
182f0 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
18300 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64  globally enabled
18310 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74  . If the paramet
18320 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65 6e  er is zero, then
18330 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a 2a   URI handling.**
18340 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73   is globally dis
18350 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20 68 61  abled. If URI ha
18360 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
18370 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20  ly enabled, all 
18380 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73  filenames.** pas
18390 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
183a0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
183b0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73  3_open_v2()], [s
183c0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
183d0 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69 65 64   or.** specified
183e0 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41 54 54   as part of [ATT
183f0 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72  ACH] commands ar
18400 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
18410 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c 65 73   URIs, regardles
18420 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65 72 20  s.** of whether 
18430 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49  or not the [SQLI
18440 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
18450 67 20 69 73 20 73 65 74 20 77 68 65 6e 20 74 68  g is set when th
18460 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
18470 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e  nnection is open
18480 65 64 2e 20 49 66 20 69 74 20 69 73 20 67 6c 6f  ed. If it is glo
18490 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20  bally disabled, 
184a0 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  filenames are.**
184b0 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65   only interprete
184c0 64 20 61 73 20 55 52 49 73 20 69 66 20 74 68 65  d as URIs if the
184d0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49   SQLITE_OPEN_URI
184e0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
184f0 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  n the.** databas
18500 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
18510 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66 61 75  opened. By defau
18520 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
18530 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
18540 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
18550 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
18560 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
18570 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
18580 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
18590 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
185a0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ned..**.** [[SQL
185b0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
185c0 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d  ING_INDEX_SCAN]]
185d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
185e0 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45  IG_COVERING_INDE
185f0 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 20 54  X_SCAN.** <dd> T
18600 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
18610 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65   a single intege
18620 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68  r argument which
18630 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
18640 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20  as.** a boolean 
18650 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62  in order to enab
18660 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68  le or disable th
18670 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
18680 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a  g indices for.**
18690 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e   full table scan
186a0 73 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f  s in the query o
186b0 70 74 69 6d 69 7a 65 72 2e 20 20 54 68 65 20 64  ptimizer.  The d
186c0 65 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69  efault setting i
186d0 73 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20  s determined.** 
186e0 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41  by the [SQLITE_A
186f0 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  LLOW_COVERING_IN
18700 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c  DEX_SCAN] compil
18710 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f  e-time option, o
18720 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20  r is "on".** if 
18730 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  that compile-tim
18740 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74  e option is omit
18750 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c  ted..** The abil
18760 69 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74  ity to disable t
18770 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69  he use of coveri
18780 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66  ng indices for f
18790 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a  ull table scans.
187a0 2a 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f  ** is because so
187b0 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63  me incorrectly c
187c0 6f 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c  oded legacy appl
187d0 69 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d  ications might m
187e0 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 61  alfunction.** ma
187f0 6c 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 20 74  lfunction when t
18800 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
18810 69 73 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f  is enabled.  Pro
18820 76 69 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69  viding the abili
18830 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65  ty to.** disable
18840 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f   the optimizatio
18850 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64  n allows the old
18860 65 72 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63  er, buggy applic
18870 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f  ation code to wo
18880 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68  rk.** without ch
18890 61 6e 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e  ange even with n
188a0 65 77 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66  ewer versions of
188b0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b   SQLite..**.** [
188c0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
188d0 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45  CACHE]] [[SQLITE
188e0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
188f0 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  E]].** <dt>SQLIT
18900 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20  E_CONFIG_PCACHE 
18910 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  and SQLITE_CONFI
18920 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c  G_GETPCACHE.** <
18930 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e  dd> These option
18940 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61  s are obsolete a
18950 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  nd should not be
18960 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64   used by new cod
18970 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72  e..** They are r
18980 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b  etained for back
18990 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c  wards compatibil
189a0 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20  ity but are now 
189b0 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c 3e  no-ops..** </dl>
189c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
189d0 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a  CONFIG_SQLLOG]].
189e0 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ** <dt>SQLITE_CO
189f0 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c  NFIG_SQLLOG.** <
18a00 64 64 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69  dd>This option i
18a10 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65  s only available
18a20 20 69 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f   if sqlite is co
18a30 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
18a40 2a 2a 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  ** SQLITE_ENABLE
18a50 5f 53 51 4c 4c 4f 47 20 70 72 65 2d 70 72 6f 63  _SQLLOG pre-proc
18a60 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
18a70 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ned. The first a
18a80 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a  rgument should.*
18a90 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  * be a pointer t
18aa0 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
18ab0 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69  type void(*)(voi
18ac0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73  d*,sqlite3*,cons
18ad0 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a  t char*, int)..*
18ae0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f  * The second sho
18af0 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28  uld be of type (
18b00 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c  void*). The call
18b10 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
18b20 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a  by the library.*
18b30 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72  * in three separ
18b40 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ate circumstance
18b50 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  s, identified by
18b60 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
18b70 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  d as the.** four
18b80 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  th parameter. If
18b90 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
18ba0 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e  meter is 0, then
18bb0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
18bc0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73  nnection.** pass
18bd0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
18be0 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75   argument has ju
18bf0 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  st been opened. 
18c00 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
18c10 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  nt.** points to 
18c20 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e  a buffer contain
18c30 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
18c40 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
18c50 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a  e file. If the.*
18c60 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
18c70 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68  er is 1, then th
18c80 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
18c90 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70  that the third p
18ca0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e  arameter.** poin
18cb0 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62  ts to has just b
18cc0 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72  een executed. Or
18cd0 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20  , if the fourth 
18ce0 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20  parameter is 2, 
18cf0 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e  then.** the conn
18d00 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73  ection being pas
18d10 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
18d20 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62  d parameter is b
18d30 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65  eing closed. The
18d40 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
18d50 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55  ter is passed NU
18d60 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e  LL In this case.
18d70 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65  .** </dl>.*/.#de
18d80 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
18d90 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 20  IG_SINGLETHREAD 
18da0 20 31 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64   1  /* nil */.#d
18db0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
18dc0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20  FIG_MULTITHREAD 
18dd0 20 20 32 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23    2  /* nil */.#
18de0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18df0 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20  NFIG_SERIALIZED 
18e00 20 20 20 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a     3  /* nil */.
18e10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
18e20 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20  ONFIG_MALLOC    
18e30 20 20 20 20 34 20 20 2f 2a 20 73 71 6c 69 74 65      4  /* sqlite
18e40 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a  3_mem_methods* *
18e50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
18e60 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f  _CONFIG_GETMALLO
18e70 43 20 20 20 20 20 35 20 20 2f 2a 20 73 71 6c 69  C     5  /* sqli
18e80 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a  te3_mem_methods*
18e90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18ea0 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
18eb0 48 20 20 20 20 20 20 20 36 20 20 2f 2a 20 76 6f  H       6  /* vo
18ec0 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74  id*, int sz, int
18ed0 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51   N */.#define SQ
18ee0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
18ef0 43 41 43 48 45 20 20 20 20 20 37 20 20 2f 2a 20  CACHE     7  /* 
18f00 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69  void*, int sz, i
18f10 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt N */.#define 
18f20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
18f30 41 50 20 20 20 20 20 20 20 20 20 20 38 20 20 2f  AP          8  /
18f40 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79  * void*, int nBy
18f50 74 65 2c 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23  te, int min */.#
18f60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
18f70 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 20 20  NFIG_MEMSTATUS  
18f80 20 20 20 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e     9  /* boolean
18f90 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
18fa0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
18fb0 20 20 20 20 20 20 20 31 30 20 20 2f 2a 20 73 71         10  /* sq
18fc0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
18fd0 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
18fe0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
18ff0 54 4d 55 54 45 58 20 20 20 20 20 31 31 20 20 2f  TMUTEX     11  /
19000 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
19010 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70  methods* */./* p
19020 72 65 76 69 6f 75 73 6c 79 20 53 51 4c 49 54 45  reviously SQLITE
19030 5f 43 4f 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c  _CONFIG_CHUNKALL
19040 4f 43 20 31 32 20 77 68 69 63 68 20 69 73 20 6e  OC 12 which is n
19050 6f 77 20 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23  ow unused. */ .#
19060 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
19070 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20  NFIG_LOOKASIDE  
19080 20 20 31 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74    13  /* int int
19090 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
190a0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
190b0 20 20 20 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f         14  /* no
190c0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
190d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
190e0 50 43 41 43 48 45 20 20 20 20 31 35 20 20 2f 2a  PCACHE    15  /*
190f0 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e   no-op */.#defin
19100 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
19110 4c 4f 47 20 20 20 20 20 20 20 20 20 20 31 36 20  LOG          16 
19120 20 2f 2a 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a   /* xFunc, void*
19130 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
19140 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 20 20 20  TE_CONFIG_URI   
19150 20 20 20 20 20 20 20 31 37 20 20 2f 2a 20 69 6e         17  /* in
19160 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
19170 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48  ITE_CONFIG_PCACH
19180 45 32 20 20 20 20 20 20 31 38 20 20 2f 2a 20 73  E2      18  /* s
19190 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65  qlite3_pcache_me
191a0 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69  thods2* */.#defi
191b0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
191c0 5f 47 45 54 50 43 41 43 48 45 32 20 20 20 31 39  _GETPCACHE2   19
191d0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61    /* sqlite3_pca
191e0 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f  che_methods2* */
191f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
19200 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f  CONFIG_COVERING_
19210 49 4e 44 45 58 5f 53 43 41 4e 20 32 30 20 20 2f  INDEX_SCAN 20  /
19220 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
19230 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
19240 51 4c 4c 4f 47 20 20 20 20 20 20 20 32 31 20 20  QLLOG       21  
19250 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64  /* xSqllog, void
19260 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  * */../*.** CAPI
19270 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
19280 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69 67  onnection Config
19290 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a  uration Options.
192a0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
192b0 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76  tants are the av
192c0 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20  ailable integer 
192d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
192e0 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61  tions that.** ca
192f0 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74  n be passed as t
19300 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
19310 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
19320 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
19330 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a  interface..**.**
19340 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74 69   New configurati
19350 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62  on options may b
19360 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
19370 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
19380 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e  Lite..** Existin
19390 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  g configuration 
193a0 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62 65  options might be
193b0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20   discontinued.  
193c0 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  Applications.** 
193d0 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68 65  should check the
193e0 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72 6f   return code fro
193f0 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  m [sqlite3_db_co
19400 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20  nfig()] to make 
19410 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  sure that.** the
19420 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 5e   call worked.  ^
19430 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  The [sqlite3_db_
19440 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
19450 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ace will return 
19460 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65  a.** non-zero [e
19470 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 20  rror code] if a 
19480 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20  discontinued or 
19490 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e 66  unsupported conf
194a0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
194b0 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a  .** is invoked..
194c0 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64  **.** <dl>.** <d
194d0 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  t>SQLITE_DBCONFI
194e0 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e  G_LOOKASIDE</dt>
194f0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
19500 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72 65  ption takes thre
19510 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  e additional arg
19520 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74 65  uments that dete
19530 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b 6c  rmine the .** [l
19540 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20  ookaside memory 
19550 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66 69  allocator] confi
19560 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  guration for the
19570 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
19580 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20  ction]..** ^The 
19590 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 28  first argument (
195a0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
195b0 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  ter to [sqlite3_
195c0 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73 20  db_config()] is 
195d0 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20  a.** pointer to 
195e0 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  a memory buffer 
195f0 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b 61  to use for looka
19600 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  side memory..** 
19610 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
19620 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53 51  ent after the SQ
19630 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
19640 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a 20  OKASIDE verb.** 
19650 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20 77  may be NULL in w
19660 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74 65  hich case SQLite
19670 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20 74   will allocate t
19680 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65 20  he.** lookaside 
19690 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75 73  buffer itself us
196a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
196b0 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65 63  loc()]. ^The sec
196c0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
196d0 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65  the.** size of e
196e0 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75  ach lookaside bu
196f0 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68 65  ffer slot.  ^The
19700 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
19710 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  is the number of
19720 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65 20  .** slots.  The 
19730 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66  size of the buff
19740 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  er in the first 
19750 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
19760 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a 2a   greater than.**
19770 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68 65   or equal to the
19780 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65 20   product of the 
19790 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72 64  second and third
197a0 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68 65   arguments.  The
197b0 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74 20   buffer.** must 
197c0 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
197d0 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79   8-byte boundary
197e0 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e  .  ^If the secon
197f0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
19800 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
19810 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e 6f  _LOOKASIDE is no
19820 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  t a multiple of 
19830 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e 61  8, it is interna
19840 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20 64  lly.** rounded d
19850 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74 20  own to the next 
19860 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c 65  smaller multiple
19870 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c 6f   of 8.  ^(The lo
19880 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 2a  okaside memory.*
19890 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
198a0 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20 63  for a database c
198b0 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f 6e  onnection can on
198c0 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77 68  ly be changed wh
198d0 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65  en that.** conne
198e0 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75 72  ction is not cur
198f0 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f 6f  rently using loo
19900 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20 6f  kaside memory, o
19910 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  r in other words
19920 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63 75  .** when the "cu
19930 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65 74  rrent value" ret
19940 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c  urned by.** [sql
19950 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d 28  ite3_db_status](
19960 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  D,[SQLITE_CONFIG
19970 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29  _LOOKASIDE],...)
19980 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79   is zero..** Any
19990 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61 6e   attempt to chan
199a0 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65  ge the lookaside
199b0 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75 72   memory configur
199c0 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61  ation when looka
199d0 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69  side.** memory i
199e0 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73 20  s in use leaves 
199f0 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  the configuratio
19a00 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64 20  n unchanged and 
19a10 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c  returns .** [SQL
19a20 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64 64  ITE_BUSY].)^</dd
19a30 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  >.**.** <dt>SQLI
19a40 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
19a50 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20  LE_FKEY</dt>.** 
19a60 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
19a70 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
19a80 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 74  ble or disable t
19a90 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  he enforcement o
19aa0 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  f.** [foreign ke
19ab0 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e 20  y constraints]. 
19ac0 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65   There should be
19ad0 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20   two additional 
19ae0 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68  arguments..** Th
19af0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
19b00 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77   is an integer w
19b10 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69 73  hich is 0 to dis
19b20 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
19b30 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65  ent,.** positive
19b40 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65 6e   to enable FK en
19b50 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65 67  forcement or neg
19b60 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20 46  ative to leave F
19b70 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a  K enforcement.**
19b80 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65   unchanged.  The
19b90 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
19ba0 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  r is a pointer t
19bb0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74  o an integer int
19bc0 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72  o which.** is wr
19bd0 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20  itten 0 or 1 to 
19be0 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65 72  indicate whether
19bf0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
19c00 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20  is off or on.** 
19c10 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63  following this c
19c20 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64  all.  The second
19c30 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
19c40 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
19c50 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61  , in.** which ca
19c60 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72 63  se the FK enforc
19c70 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69 73  ement setting is
19c80 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62 61   not reported ba
19c90 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ck. </dd>.**.** 
19ca0 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e  <dt>SQLITE_DBCON
19cb0 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47  FIG_ENABLE_TRIGG
19cc0 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  ER</dt>.** <dd> 
19cd0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
19ce0 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f  used to enable o
19cf0 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41 54  r disable [CREAT
19d00 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
19d10 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65 20  gers]..** There 
19d20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61 64  should be two ad
19d30 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
19d40 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ts..** The first
19d50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e 20   argument is an 
19d60 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69 73  integer which is
19d70 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74 72   0 to disable tr
19d80 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69 74  iggers,.** posit
19d90 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74 72  ive to enable tr
19da0 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74 69  iggers or negati
19db0 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65 20  ve to leave the 
19dc0 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67 65  setting unchange
19dd0 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64  d..** The second
19de0 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20   parameter is a 
19df0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e  pointer to an in
19e00 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63 68  teger into which
19e10 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20 30  .** is written 0
19e20 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61 74   or 1 to indicat
19e30 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67 65  e whether trigge
19e40 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20  rs are disabled 
19e50 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f  or enabled.** fo
19e60 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c  llowing this cal
19e70 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70  l.  The second p
19e80 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20  arameter may be 
19e90 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
19ea0 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65  in.** which case
19eb0 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65 74   the trigger set
19ec0 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f  ting is not repo
19ed0 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e  rted back. </dd>
19ee0 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a  .**.** </dl>.*/.
19ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
19f00 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
19f10 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f 2a  E       1001  /*
19f20 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20 2a   void* int int *
19f30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
19f40 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45  _DBCONFIG_ENABLE
19f50 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20 20  _FKEY     1002  
19f60 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23  /* int int* */.#
19f70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42  define SQLITE_DB
19f80 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52  CONFIG_ENABLE_TR
19f90 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a 20  IGGER  1003  /* 
19fa0 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a  int int* */.../*
19fb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 6e  .** CAPI3REF: En
19fc0 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65 20  able Or Disable 
19fd0 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20  Extended Result 
19fe0 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Codes.**.** ^The
19ff0 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65   sqlite3_extende
1a000 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
1a010 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65 73   routine enables
1a020 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65   or disables the
1a030 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1a040 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61 74  sult codes] feat
1a050 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20 5e  ure of SQLite. ^
1a060 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65 73  The extended res
1a070 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72 65  ult.** codes are
1a080 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66   disabled by def
1a090 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72 69  ault for histori
1a0a0 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
1a0b0 79 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y..*/.SQLITE_API
1a0c0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74   int sqlite3_ext
1a0d0 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
1a0e0 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  es(sqlite3*, int
1a0f0 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20   onoff);../*.** 
1a100 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49  CAPI3REF: Last I
1a110 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a  nsert Rowid.**.*
1a120 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e  * ^Each entry in
1a130 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65   an SQLite table
1a140 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
1a150 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
1a160 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
1a170 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
1a180 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
1a190 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
1a1a0 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
1a1b0 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
1a1c0 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
1a1d0 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
1a1e0 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
1a1f0 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
1a200 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
1a210 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
1a220 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
1a230 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
1a240 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
1a250 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
1a260 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
1a270 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
1a280 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
1a290 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
1a2a0 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20  * ^This routine 
1a2b0 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77  returns the [row
1a2c0 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20  id] of the most 
1a2d0 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73  recent.** succes
1a2e0 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e  sful [INSERT] in
1a2f0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
1a300 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61  from the [databa
1a310 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a  se connection].*
1a320 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61  * in the first a
1a330 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f 66  rgument.  ^As of
1a340 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1a350 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75 74  3.7.7, this rout
1a360 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73 20  ines.** records 
1a370 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
1a380 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f 72  rowid of both or
1a390 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61 6e  dinary tables an
1a3a0 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  d [virtual table
1a3b0 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73 75  s]..** ^If no su
1a3c0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
1a3d0 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72 20  ]s.** have ever 
1a3e0 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61 74  occurred on that
1a3f0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a400 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72 65  tion, zero is re
1a410 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  turned..**.** ^(
1a420 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f  If an [INSERT] o
1a430 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74  ccurs within a t
1a440 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e  rigger or within
1a450 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
1a460 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68  e].** method, th
1a470 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  en this routine 
1a480 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20  will return the 
1a490 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69  [rowid] of the i
1a4a0 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61  nserted.** row a
1a4b0 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72  s long as the tr
1a4c0 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c  igger or virtual
1a4d0 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73   table method is
1a4e0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74   running..** But
1a4f0 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65   once the trigge
1a500 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62  r or virtual tab
1a510 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20  le method ends, 
1a520 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a530 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72  ed .** by this r
1a540 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74  outine reverts t
1a550 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65  o what it was be
1a560 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
1a570 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74   or virtual.** t
1a580 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61  able method bega
1a590 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b  n.)^.**.** ^An [
1a5a0 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69  INSERT] that fai
1a5b0 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73  ls due to a cons
1a5c0 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
1a5d0 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63   is not a.** suc
1a5e0 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
1a5f0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68   and does not ch
1a600 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72  ange the value r
1a610 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a  eturned by this.
1a620 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68  ** routine.  ^Th
1a630 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49  us INSERT OR FAI
1a640 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e  L, INSERT OR IGN
1a650 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52  ORE, INSERT OR R
1a660 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20  OLLBACK,.** and 
1a670 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20  INSERT OR ABORT 
1a680 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20  make no changes 
1a690 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  to the return va
1a6a0 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72  lue of this.** r
1a6b0 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69  outine when thei
1a6c0 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c  r insertion fail
1a6d0 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52  s.  ^(When INSER
1a6e0 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20  T OR REPLACE.** 
1a6f0 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e  encounters a con
1a700 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
1a710 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66  n, it does not f
1a720 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53  ail.  The.** INS
1a730 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f  ERT continues to
1a740 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65   completion afte
1a750 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20  r deleting rows 
1a760 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74  that caused.** t
1a770 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72  he constraint pr
1a780 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20  oblem so INSERT 
1a790 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20  OR REPLACE will 
1a7a0 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a  always change.**
1a7b0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
1a7c0 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66  e of this interf
1a7d0 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f  ace.)^.**.** ^Fo
1a7e0 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f  r the purposes o
1a7f0 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  f this routine, 
1a800 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63  an [INSERT] is c
1a810 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20  onsidered to.** 
1a820 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76  be successful ev
1a830 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73  en if it is subs
1a840 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20  equently rolled 
1a850 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  back..**.** This
1a860 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63   function is acc
1a870 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73  essible to SQL s
1a880 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68  tatements via th
1a890 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72  e.** [last_inser
1a8a0 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75  t_rowid() SQL fu
1a8b0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1a8c0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1a8d0 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e  ead performs a n
1a8e0 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74  ew [INSERT] on t
1a8f0 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62  he same.** datab
1a900 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  ase connection w
1a910 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65  hile the [sqlite
1a920 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1a930 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69  wid()].** functi
1a940 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e  on is running an
1a950 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74  d thus changes t
1a960 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b  he last insert [
1a970 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20  rowid],.** then 
1a980 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
1a990 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c  ed by [sqlite3_l
1a9a0 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
1a9b0 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64  ()] is.** unpred
1a9c0 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68  ictable and migh
1a9d0 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68  t not equal eith
1a9e0 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68  er the old or th
1a9f0 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e  e new.** last in
1aa00 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f  sert [rowid]..*/
1aa10 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
1aa20 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
1aa30 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
1aa40 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
1aa50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1aa60 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
1aa70 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
1aa80 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
1aa90 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
1aaa0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
1aab0 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
1aac0 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
1aad0 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
1aae0 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
1aaf0 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
1ab00 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
1ab10 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
1ab20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1ab30 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
1ab40 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1ab50 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  eter..** ^(Only 
1ab60 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
1ab70 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
1ab80 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
1ab90 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
1aba0 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
1abb0 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
1abc0 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
1abd0 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
1abe0 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72  y.** triggers or
1abf0 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
1ac00 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63  tions] are not c
1ac10 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68  ounted.)^ Use th
1ac20 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
1ac30 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
1ac40 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
1ac50 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
1ac60 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
1ac70 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
1ac80 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
1ac90 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
1aca0 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
1acb0 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  ** ^Changes to a
1acc0 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73   view that are s
1acd0 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b  imulated by an [
1ace0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1acf0 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  er].** are not c
1ad00 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65  ounted.  Only re
1ad10 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73  al table changes
1ad20 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
1ad30 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61  .** ^(A "row cha
1ad40 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
1ad50 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
1ad60 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
1ad70 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
1ad80 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
1ad90 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
1ada0 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
1adb0 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
1adc0 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
1add0 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
1ade0 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
1adf0 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
1ae00 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
1ae10 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
1ae20 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
1ae30 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
1ae40 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
1ae50 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
1ae60 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22  ges.)^.**.** A "
1ae70 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
1ae80 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
1ae90 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
1aea0 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
1aeb0 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
1aec0 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52   of a [CREATE TR
1aed0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
1aee0 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73  . .** Most SQL s
1aef0 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
1af00 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
1af10 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
1af20 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
1af30 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
1af40 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
1af50 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
1af60 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
1af70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
1af80 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
1af90 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
1afa0 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
1afb0 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
1afc0 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
1afd0 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
1afe0 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
1aff0 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  uration..**.** ^
1b000 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
1b010 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
1b020 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
1b030 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
1b040 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
1b050 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
1b060 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  t..**.** ^This f
1b070 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
1b080 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
1b090 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
1b0a0 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
1b0b0 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
1b0c0 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
1b0d0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
1b0e0 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
1b0f0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
1b100 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e  *.** ^Thus, when
1b110 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
1b120 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
1b130 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
1b140 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
1b150 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
1b160 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
1b170 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
1b180 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
1b190 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
1b1a0 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
1b1b0 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f   ^(Within the bo
1b1c0 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
1b1d0 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
1b1e0 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
1b1f0 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
1b200 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
1b210 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
1b220 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
1b230 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
1b240 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
1b250 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
1b260 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
1b270 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
1b280 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
1b290 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
1b2a0 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
1b2b0 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
1b2c0 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
1b2d0 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
1b2e0 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
1b2f0 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
1b300 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  xt.)^.**.** See 
1b310 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
1b320 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
1b330 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
1b340 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
1b350 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
1b360 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
1b370 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
1b380 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
1b390 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
1b3a0 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
1b3b0 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
1b3c0 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
1b3d0 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
1b3e0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1b3f0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
1b400 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
1b410 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1b420 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1b430 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1b440 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
1b450 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
1b460 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
1b470 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
1b480 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
1b490 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
1b4a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
1b4b0 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
1b4c0 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e  es caused by [IN
1b4d0 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54  SERT],.** [UPDAT
1b4e0 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
1b4f0 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
1b500 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
1b510 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
1b520 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63  ened..** ^(The c
1b530 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
1b540 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
1b550 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65  hanges() include
1b560 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a  s all changes.**
1b570 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54   from all [CREAT
1b580 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
1b590 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e  ger] contexts an
1b5a0 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62  d changes made b
1b5b0 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  y.** [foreign ke
1b5c0 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65  y actions]. Howe
1b5d0 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
1b5e0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
1b5f0 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
1b600 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
1b610 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
1b620 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
1b630 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
1b640 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
1b650 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
1b660 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
1b670 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
1b680 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
1b690 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
1b6a0 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
1b6b0 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
1b6c0 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
1b6d0 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
1b6e0 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
1b6f0 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
1b700 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
1b710 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .)^.** ^The sqli
1b720 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1b730 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  s() function cou
1b740 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20  nts the changes 
1b750 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68  as soon as.** th
1b760 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
1b770 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
1b780 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
1b790 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
1b7a0 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64  dle.** is passed
1b7b0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
1b7c0 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
1b7d0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
1b7e0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
1b7f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
1b800 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
1b810 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
1b820 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
1b830 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
1b840 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
1b850 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
1b860 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
1b870 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
1b880 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
1b890 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1b8a0 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
1b8b0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
1b8c0 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
1b8d0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
1b8e0 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
1b8f0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
1b900 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
1b910 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1b920 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
1b930 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
1b940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b950 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
1b960 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
1b970 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ry.**.** ^This f
1b980 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
1b990 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
1b9a0 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
1b9b0 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
1b9c0 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
1b9d0 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
1b9e0 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
1b9f0 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
1ba00 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
1ba10 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
1ba20 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
1ba30 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
1ba40 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
1ba50 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
1ba60 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
1ba70 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
1ba80 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
1ba90 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
1baa0 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
1bab0 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
1bac0 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
1bad0 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
1bae0 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
1baf0 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
1bb00 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
1bb10 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
1bb20 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
1bb30 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
1bb40 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
1bb50 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
1bb60 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
1bb70 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
1bb80 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
1bb90 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
1bba0 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
1bbb0 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
1bbc0 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
1bbd0 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
1bbe0 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
1bbf0 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
1bc00 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
1bc10 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
1bc20 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
1bc30 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
1bc40 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
1bc50 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
1bc60 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
1bc70 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
1bc80 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
1bc90 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
1bca0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
1bcb0 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
1bcc0 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
1bcd0 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
1bce0 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
1bcf0 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
1bd00 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
1bd10 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
1bd20 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
1bd30 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
1bd40 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
1bd50 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
1bd60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1bd70 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
1bd80 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
1bd90 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
1bda0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
1bdb0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
1bdc0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
1bdd0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
1bde0 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
1bdf0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
1be00 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
1be10 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
1be20 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
1be30 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
1be40 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
1be50 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
1be60 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
1be70 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
1be80 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
1be90 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
1bea0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
1beb0 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
1bec0 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
1bed0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
1bee0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
1bef0 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
1bf00 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
1bf10 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
1bf20 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
1bf30 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
1bf40 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
1bf50 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
1bf60 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
1bf70 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
1bf80 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
1bf90 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1bfa0 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
1bfb0 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
1bfc0 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
1bfd0 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
1bfe0 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
1bff0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
1c000 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
1c010 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
1c020 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1c030 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
1c040 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
1c050 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
1c060 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
1c070 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
1c080 61 70 70 65 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45  appen..*/.SQLITE
1c090 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
1c0a0 33 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69  3_interrupt(sqli
1c0b0 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
1c0c0 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e  PI3REF: Determin
1c0d0 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74  e If An SQL Stat
1c0e0 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74  ement Is Complet
1c0f0 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  e.**.** These ro
1c100 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75  utines are usefu
1c110 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64  l during command
1c120 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64  -line input to d
1c130 65 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a  etermine if the.
1c140 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74  ** currently ent
1c150 65 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20  ered text seems 
1c160 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65  to form a comple
1c170 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1c180 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69   or.** if additi
1c190 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65  onal input is ne
1c1a0 65 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64  eded before send
1c1b0 69 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74  ing the text int
1c1c0 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20  o.** SQLite for 
1c1d0 70 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65  parsing.  ^These
1c1e0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1c1f0 20 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20   1 if the input 
1c200 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72  string.** appear
1c210 73 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65  s to be a comple
1c220 74 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  te SQL statement
1c230 2e 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20  .  ^A statement 
1c240 69 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a  is judged to be.
1c250 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69  ** complete if i
1c260 74 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65  t ends with a se
1c270 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e  micolon token an
1c280 64 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69  d is not a prefi
1c290 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66  x of a.** well-f
1c2a0 6f 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49  ormed CREATE TRI
1c2b0 47 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20  GGER statement. 
1c2c0 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61   ^Semicolons tha
1c2d0 74 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77  t are embedded w
1c2e0 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20  ithin.** string 
1c2f0 6c 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74  literals or quot
1c300 65 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61  ed identifier na
1c310 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20  mes or comments 
1c320 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70  are not.** indep
1c330 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74  endent tokens (t
1c340 68 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20  hey are part of 
1c350 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69  the token in whi
1c360 63 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65  ch they are.** e
1c370 6d 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75  mbedded) and thu
1c380 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61  s do not count a
1c390 73 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65  s a statement te
1c3a0 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74  rminator.  ^Whit
1c3b0 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f  espace.** and co
1c3c0 6d 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c  mments that foll
1c3d0 6f 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d  ow the final sem
1c3e0 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72  icolon are ignor
1c3f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
1c400 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1c410 20 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d   0 if the statem
1c420 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74  ent is incomplet
1c430 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d  e.  ^If a.** mem
1c440 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
1c450 61 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54  ails, then SQLIT
1c460 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72  E_NOMEM is retur
1c470 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ned..**.** ^Thes
1c480 65 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f  e routines do no
1c490 74 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20  t parse the SQL 
1c4a0 73 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a  statements thus.
1c4b0 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65  ** will not dete
1c4c0 63 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79  ct syntactically
1c4d0 20 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a   incorrect SQL..
1c4e0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74  **.** ^(If SQLit
1c4f0 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69  e has not been i
1c500 6e 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67  nitialized using
1c510 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
1c520 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a  lize()] prior .*
1c530 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71  * to invoking sq
1c540 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
1c550 28 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  () then sqlite3_
1c560 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20  initialize() is 
1c570 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d  invoked.** autom
1c580 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69  atically by sqli
1c590 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
1c5a0 2e 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69  .  If that initi
1c5b0 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c  alization fails,
1c5c0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74  .** then the ret
1c5d0 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
1c5e0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
1c5f0 36 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d  6() will be non-
1c600 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65  zero.** regardle
1c610 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
1c620 20 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53   not the input S
1c630 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29  QL is complete.)
1c640 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ^.**.** The inpu
1c650 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
1c660 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62  mplete()] must b
1c670 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  e a zero-termina
1c680 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72  ted.** UTF-8 str
1c690 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  ing..**.** The i
1c6a0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
1c6b0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d  _complete16()] m
1c6c0 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
1c6d0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
1c6e0 31 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74  16 string in nat
1c6f0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a  ive byte order..
1c700 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
1c710 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  t sqlite3_comple
1c720 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  te(const char *s
1c730 71 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ql);.SQLITE_API 
1c740 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
1c750 6c 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69  lete16(const voi
1c760 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  d *sql);../*.** 
1c770 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74  CAPI3REF: Regist
1c780 65 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f  er A Callback To
1c790 20 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42   Handle SQLITE_B
1c7a0 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a  USY Errors.**.**
1c7b0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
1c7c0 65 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66  ets a callback f
1c7d0 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67  unction that mig
1c7e0 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  ht be invoked wh
1c7f0 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74  enever.** an att
1c800 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20  empt is made to 
1c810 6f 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  open a database 
1c820 74 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68  table that anoth
1c830 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20  er thread.** or 
1c840 70 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b  process has lock
1c850 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1c860 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20  e busy callback 
1c870 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53  is NULL, then [S
1c880 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b  QLITE_BUSY] or [
1c890 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
1c8a0 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75  CKED].** is retu
1c8b0 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
1c8c0 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69   upon encounteri
1c8d0 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49  ng the lock.  ^I
1c8e0 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
1c8f0 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  ack.** is not NU
1c900 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c  LL, then the cal
1c910 6c 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69  lback might be i
1c920 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20  nvoked with two 
1c930 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  arguments..**.**
1c940 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
1c950 6d 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79  ment to the busy
1c960 20 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f   handler is a co
1c970 70 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20  py of the void* 
1c980 70 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a  pointer which.**
1c990 20 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72   is the third ar
1c9a0 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
1c9b0 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29  3_busy_handler()
1c9c0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  .  ^The second a
1c9d0 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68  rgument to.** th
1c9e0 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63  e busy handler c
1c9f0 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e  allback is the n
1ca00 75 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74  umber of times t
1ca10 68 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e  hat the busy han
1ca20 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e  dler has.** been
1ca30 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69   invoked for thi
1ca40 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e  s locking event.
1ca50 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73    ^If the.** bus
1ca60 79 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  y callback retur
1ca70 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64  ns 0, then no ad
1ca80 64 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74  ditional attempt
1ca90 73 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a  s are made to.**
1caa0 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61   access the data
1cab0 62 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45  base and [SQLITE
1cac0 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54  _BUSY] or [SQLIT
1cad0 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d  E_IOERR_BLOCKED]
1cae0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
1caf0 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
1cb00 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
1cb10 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72  ro, then another
1cb20 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d   attempt.** is m
1cb30 61 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20  ade to open the 
1cb40 64 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61  database for rea
1cb50 64 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63  ding and the cyc
1cb60 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a  le repeats..**.*
1cb70 2a 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f  * The presence o
1cb80 66 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72  f a busy handler
1cb90 20 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e   does not guaran
1cba0 74 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c  tee that it will
1cbb0 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77   be invoked.** w
1cbc0 68 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63  hen there is loc
1cbd0 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49  k contention. ^I
1cbe0 66 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69  f SQLite determi
1cbf0 6e 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e  nes that invokin
1cc00 67 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61  g the busy.** ha
1cc10 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75  ndler could resu
1cc20 6c 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b  lt in a deadlock
1cc30 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65  , it will go ahe
1cc40 61 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53  ad and return [S
1cc50 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f  QLITE_BUSY].** o
1cc60 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
1cc70 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64  BLOCKED] instead
1cc80 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65   of invoking the
1cc90 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
1cca0 2a 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65  * Consider a sce
1ccb0 6e 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20  nario where one 
1ccc0 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69  process is holdi
1ccd0 6e 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74  ng a read lock t
1cce0 68 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79  hat.** it is try
1ccf0 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  ing to promote t
1cd00 6f 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  o a reserved loc
1cd10 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e  k and.** a secon
1cd20 64 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c  d process is hol
1cd30 64 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20  ding a reserved 
1cd40 6c 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20  lock that it is 
1cd50 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f  trying.** to pro
1cd60 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75  mote to an exclu
1cd70 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20  sive lock.  The 
1cd80 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61  first process ca
1cd90 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20  nnot proceed.** 
1cda0 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
1cdb0 6f 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63  ocked by the sec
1cdc0 6f 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f  ond and the seco
1cdd0 6e 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  nd process canno
1cde0 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63  t.** proceed bec
1cdf0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
1ce00 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e  ed by the first.
1ce10 20 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73    If both proces
1ce20 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68  ses.** invoke th
1ce30 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c  e busy handlers,
1ce40 20 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61   neither will ma
1ce50 6b 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e  ke any progress.
1ce60 20 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20    Therefore,.** 
1ce70 53 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b  SQLite returns [
1ce80 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72  SQLITE_BUSY] for
1ce90 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
1cea0 73 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20  ss, hoping that 
1ceb0 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64  this.** will ind
1cec0 75 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72  uce the first pr
1ced0 6f 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65  ocess to release
1cee0 20 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61   its read lock a
1cef0 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20  nd allow.** the 
1cf00 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74  second process t
1cf10 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a  o proceed..**.**
1cf20 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75   ^The default bu
1cf30 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e  sy callback is N
1cf40 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
1cf50 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72  [SQLITE_BUSY] er
1cf60 72 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64  ror is converted
1cf70 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   to [SQLITE_IOER
1cf80 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68  R_BLOCKED].** wh
1cf90 65 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20  en SQLite is in 
1cfa0 74 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20  the middle of a 
1cfb0 6c 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f  large transactio
1cfc0 6e 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a  n where all the.
1cfd0 2a 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20  ** changes will 
1cfe0 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65  not fit into the
1cff0 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65   in-memory cache
1d000 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a  .  SQLite will.*
1d010 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61  * already hold a
1d020 20 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f   RESERVED lock o
1d030 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
1d040 69 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64  ile, but it need
1d050 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  s.** to promote 
1d060 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43  this lock to EXC
1d070 4c 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69  LUSIVE so that i
1d080 74 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68  t can spill cach
1d090 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20  e.** pages into 
1d0a0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
1d0b0 65 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74  e without harm t
1d0c0 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20  o concurrent.** 
1d0d0 72 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74  readers.  ^If it
1d0e0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72   is unable to pr
1d0f0 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20  omote the lock, 
1d100 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  then the in-memo
1d110 72 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c  ry.** cache will
1d120 20 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69   be left in an i
1d130 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74  nconsistent stat
1d140 65 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72  e and so the err
1d150 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72  or.** code is pr
1d160 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20  omoted from the 
1d170 72 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67  relatively benig
1d180 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
1d190 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73  to.** the more s
1d1a0 65 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f  evere [SQLITE_IO
1d1b0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e  ERR_BLOCKED].  ^
1d1c0 54 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20  This error code 
1d1d0 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72  promotion.** for
1d1e0 63 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63  ces an automatic
1d1f0 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65   rollback of the
1d200 20 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74   changes.  See t
1d210 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f  he.** <a href="/
1d220 63 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43  cvstrac/wiki?p=C
1d230 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69  orruptionFollowi
1d240 6e 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a  ngBusyError">.**
1d250 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f   CorruptionFollo
1d260 77 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61  wingBusyError</a
1d270 3e 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20  > wiki page for 
1d280 61 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20  a discussion of 
1d290 77 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69  why.** this is i
1d2a0 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20  mportant..**.** 
1d2b0 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79  ^(There can only
1d2c0 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73   be a single bus
1d2d0 79 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65  y handler define
1d2e0 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64  d for each.** [d
1d2f0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1d300 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20  on].  Setting a 
1d310 6e 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72  new busy handler
1d320 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70   clears any.** p
1d330 72 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61  reviously set ha
1d340 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20  ndler.)^  ^Note 
1d350 74 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  that calling [sq
1d360 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f  lite3_busy_timeo
1d370 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c  ut()].** will al
1d380 73 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20  so set or clear 
1d390 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
1d3a0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
1d3b0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1d3c0 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
1d3d0 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
1d3e0 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
1d3f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
1d400 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
1d410 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e  usy handler.  An
1d420 79 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a  y such actions.*
1d430 2a 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65  * result in unde
1d440 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
1d450 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61  ** .** A busy ha
1d460 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63  ndler must not c
1d470 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73  lose the databas
1d480 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1d490 6f 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  or [prepared sta
1d4a0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76  tement] that inv
1d4b0 6f 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61  oked the busy ha
1d4c0 6e 64 6c 65 72 2e 0a 2a 2f 0a 53 51 4c 49 54 45  ndler..*/.SQLITE
1d4d0 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33  _API int sqlite3
1d4e0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 73 71  _busy_handler(sq
1d4f0 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76  lite3*, int(*)(v
1d500 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69 64 2a  oid*,int), void*
1d510 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d520 45 46 3a 20 53 65 74 20 41 20 42 75 73 79 20 54  EF: Set A Busy T
1d530 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68  imeout.**.** ^Th
1d540 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73 20  is routine sets 
1d550 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  a [sqlite3_busy_
1d560 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79 20 68  handler | busy h
1d570 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73 6c 65  andler] that sle
1d580 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73 70 65  eps.** for a spe
1d590 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20 6f 66  cified amount of
1d5a0 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74 61 62   time when a tab
1d5b0 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20 20 5e  le is locked.  ^
1d5c0 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77  The handler.** w
1d5d0 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74 69 70  ill sleep multip
1d5e0 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c 20 61  le times until a
1d5f0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
1d600 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
1d610 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20 61 63  eping.** have ac
1d620 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41 66 74  cumulated.  ^Aft
1d630 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  er at least "ms"
1d640 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
1d650 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20 74 68   sleeping,.** th
1d660 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75 72 6e  e handler return
1d670 73 20 30 20 77 68 69 63 68 20 63 61 75 73 65 73  s 0 which causes
1d680 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1d690 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 5b  ] to return.** [
1d6a0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20  SQLITE_BUSY] or 
1d6b0 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c  [SQLITE_IOERR_BL
1d6c0 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43  OCKED]..**.** ^C
1d6d0 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f 75 74  alling this rout
1d6e0 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72 67 75  ine with an argu
1d6f0 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e 20 6f  ment less than o
1d700 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 0a  r equal to zero.
1d710 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61 6c 6c  ** turns off all
1d720 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2e 0a   busy handlers..
1d730 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63 61  **.** ^(There ca
1d740 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e 67  n only be a sing
1d750 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  le busy handler 
1d760 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72  for a particular
1d770 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
1d780 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20 61 6e  nnection] any an
1d790 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20  y given moment. 
1d7a0 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75 73 79   If another busy
1d7b0 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61 73 20   handler.** was 
1d7c0 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e 67 20  defined  (using 
1d7d0 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61  [sqlite3_busy_ha
1d7e0 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f 72 20  ndler()]) prior 
1d7f0 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68  to calling.** th
1d800 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68 61 74  is routine, that
1d810 20 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e 64   other busy hand
1d820 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64 2e 29  ler is cleared.)
1d830 5e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ^.*/.SQLITE_API 
1d840 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
1d850 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
1d860 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
1d870 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
1d880 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
1d890 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
1d8a0 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
1d8b0 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
1d8c0 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
1d8d0 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
1d8e0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
1d8f0 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
1d900 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
1d910 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1d920 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1d930 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1d940 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1d950 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1d960 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1d970 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1d980 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1d990 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1d9a0 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1d9b0 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1d9c0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1d9d0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1d9e0 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1d9f0 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1da00 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1da10 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1da20 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1da30 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1da40 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1da50 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1da60 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1da70 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1da80 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1da90 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1daa0 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1dab0 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1dac0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1dad0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1dae0 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1daf0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1db00 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1db10 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1db20 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1db30 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1db40 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1db50 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1db60 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1db70 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1db80 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1db90 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1dba0 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1dbb0 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1dbc0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1dbd0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1dbe0 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1dbf0 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1dc00 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1dc10 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1dc20 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1dc30 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1dc40 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1dc50 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1dc60 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1dc70 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1dc80 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1dc90 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1dca0 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1dcb0 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1dcc0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1dcd0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1dce0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1dcf0 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1dd00 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1dd10 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1dd20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1dd30 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1dd40 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1dd50 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1dd60 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1dd70 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1dd80 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1dd90 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1dda0 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1ddb0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1ddc0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1ddd0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1dde0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1ddf0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1de00 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1de10 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1de20 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1de30 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1de40 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1de50 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1de60 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1de70 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1de80 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1de90 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1dea0 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1deb0 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1dec0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1ded0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1dee0 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1def0 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1df00 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1df10 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1df20 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1df30 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1df40 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1df50 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1df60 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1df70 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1df80 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1df90 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1dfa0 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1dfb0 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1dfc0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1dfd0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1dfe0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1dff0 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1e000 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1e010 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1e020 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1e030 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1e040 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1e050 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1e060 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1e070 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1e080 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1e090 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1e0a0 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1e0b0 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1e0c0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1e0d0 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1e0e0 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1e0f0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1e100 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1e110 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1e120 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1e130 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1e140 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1e150 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1e160 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1e170 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1e180 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1e190 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1e1a0 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1e1b0 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1e1c0 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1e1d0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1e1e0 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1e1f0 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1e200 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1e210 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1e220 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1e230 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1e240 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1e250 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1e260 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1e270 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1e280 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1e290 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1e2a0 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1e2b0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1e2c0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1e2d0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1e2e0 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1e2f0 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1e300 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1e310 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1e320 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1e330 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1e340 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1e350 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1e360 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1e370 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1e380 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1e390 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1e3a0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1e3b0 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1e3c0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1e3d0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1e3e0 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1e3f0 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1e400 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1e410 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1e420 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1e430 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1e440 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1e450 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1e460 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1e470 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1e480 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1e490 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1e4a0 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1e4b0 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1e4c0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1e4d0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 53  _errmsg()]..*/.S
1e4e0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
1e4f0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1e500 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
1e510 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
1e520 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
1e530 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
1e540 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74  ql,     /* SQL t
1e550 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a  o be evaluated *
1e560 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52  /.  char ***pazR
1e570 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73  esult,    /* Res
1e580 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75 65 72  ults of the quer
1e590 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f  y */.  int *pnRo
1e5a0 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  w,           /* 
1e5b0 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74  Number of result
1e5c0 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65   rows written he
1e5d0 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43  re */.  int *pnC
1e5e0 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a  olumn,        /*
1e5f0 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c   Number of resul
1e600 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65  t columns writte
1e610 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72  n here */.  char
1e620 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20   **pzErrmsg     
1e630 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77    /* Error msg w
1e640 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29  ritten here */.)
1e650 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69  ;.SQLITE_API voi
1e660 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74  d sqlite3_free_t
1e670 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73 75  able(char **resu
1e680 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  lt);../*.** CAPI
1e690 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64 20  3REF: Formatted 
1e6a0 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67 20  String Printing 
1e6b0 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1e6c0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
1e6d0 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20 6f  re work-alikes o
1e6e0 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29 22  f the "printf()"
1e6f0 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63 74   family of funct
1e700 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68 65  ions.** from the
1e710 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
1e720 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ary..**.** ^The 
1e730 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
1e740 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76 6d  ) and sqlite3_vm
1e750 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65  printf() routine
1e760 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a 2a  s write their.**
1e770 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d 65   results into me
1e780 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
1e790 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
1e7a0 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 74  oc()]..** The st
1e7b0 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62  rings returned b
1e7c0 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75 74  y these two rout
1e7d0 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a 2a  ines should be.*
1e7e0 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b 73  * released by [s
1e7f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 20  qlite3_free()]. 
1e800 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73 20   ^Both routines 
1e810 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c 4c  return a.** NULL
1e820 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71 6c   pointer if [sql
1e830 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 69  ite3_malloc()] i
1e840 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f  s unable to allo
1e850 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20 6d  cate enough.** m
1e860 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
1e870 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
1e880 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ng..**.** ^(The 
1e890 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1e8a0 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73 69  () routine is si
1e8b0 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69 6e  milar to "snprin
1e8c0 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74 68  tf()" from.** th
1e8d0 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1e8e0 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75 6c  rary.  The resul
1e8f0 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74  t is written int
1e900 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72 20  o the.** buffer 
1e910 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65 20  supplied as the 
1e920 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1e930 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20 67   whose size is g
1e940 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20 66  iven by.** the f
1e950 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 20  irst parameter. 
1e960 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f 72  Note that the or
1e970 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66 69  der of the.** fi
1e980 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74 65  rst two paramete
1e990 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20 66  rs is reversed f
1e9a0 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e 29  rom snprintf().)
1e9b0 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a 2a  ^  This is an.**
1e9c0 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63 69   historical acci
1e9d0 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f 74  dent that cannot
1e9e0 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f 75   be fixed withou
1e9f0 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62 61  t breaking.** ba
1ea00 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
1ea10 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20 61  ility.  ^(Note a
1ea20 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65 33  lso that sqlite3
1ea30 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 72  _snprintf().** r
1ea40 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
1ea50 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20 69   to its buffer i
1ea60 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e 75  nstead of the nu
1ea70 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72 61  mber of.** chara
1ea80 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20 77  cters actually w
1ea90 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 20  ritten into the 
1eaa0 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61 64  buffer.)^  We ad
1eab0 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  mit that.** the 
1eac0 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63  number of charac
1ead0 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f 75  ters written wou
1eae0 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73 65  ld be a more use
1eaf0 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61  ful return.** va
1eb00 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e 6f  lue but we canno
1eb10 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d 70  t change the imp
1eb20 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73  lementation of s
1eb30 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1eb40 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75 74  ).** now without
1eb50 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61 74   breaking compat
1eb60 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ibility..**.** ^
1eb70 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 62  As long as the b
1eb80 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67 72  uffer size is gr
1eb90 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 2c  eater than zero,
1eba0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1ebb0 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65 65  f().** guarantee
1ebc0 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66 65  s that the buffe
1ebd0 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72 6f  r is always zero
1ebe0 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54  -terminated.  ^T
1ebf0 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61  he first.** para
1ec00 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68 65  meter "n" is the
1ec10 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74   total size of t
1ec20 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c 75  he buffer, inclu
1ec30 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a 2a  ding space for.*
1ec40 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69  * the zero termi
1ec50 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20 6c  nator.  So the l
1ec60 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74 68  ongest string th
1ec70 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c 65  at can be comple
1ec80 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e 20  tely.** written 
1ec90 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61 72  will be n-1 char
1eca0 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  acters..**.** ^T
1ecb0 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70 72  he sqlite3_vsnpr
1ecc0 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69  intf() routine i
1ecd0 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72 73  s a varargs vers
1ece0 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1ecf0 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a 2a  nprintf()..**.**
1ed00 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1ed10 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73 6f  all implement so
1ed20 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 6f  me additional fo
1ed30 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74 69  rmatting.** opti
1ed40 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73 65  ons that are use
1ed50 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75 63  ful for construc
1ed60 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d 65  ting SQL stateme
1ed70 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20 74  nts..** All of t
1ed80 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66 28  he usual printf(
1ed90 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  ) formatting opt
1eda0 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e 20  ions apply.  In 
1edb0 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65 0a  addition, there.
1edc0 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c 20  ** is are "%q", 
1edd0 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20 6f  "%Q", and "%z" o
1ede0 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ptions..**.** ^(
1edf0 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77 6f  The %q option wo
1ee00 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20 74  rks like %s in t
1ee10 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75 74  hat it substitut
1ee20 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  es a nul-termina
1ee30 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66 72  ted.** string fr
1ee40 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20  om the argument 
1ee50 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61 6c  list.  But %q al
1ee60 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72 79  so doubles every
1ee70 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 2e   '\'' character.
1ee80 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67 6e  .** %q is design
1ee90 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69 64  ed for use insid
1eea0 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72  e a string liter
1eeb0 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c 69  al.)^  By doubli
1eec0 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a 20  ng each '\''.** 
1eed0 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73 63  character it esc
1eee0 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61 63  apes that charac
1eef0 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20 69  ter and allows i
1ef00 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65 64  t to be inserted
1ef10 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74 72   into.** the str
1ef20 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 65  ing..**.** For e
1ef30 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20 74  xample, assume t
1ef40 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61 62  he string variab
1ef50 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69 6e  le zText contain
1ef60 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f 77  s text as follow
1ef70 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1ef80 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1ef90 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49 74  har *zText = "It
1efa0 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21 22  's a happy day!"
1efb0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
1efc0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f  ckquote>.**.** O
1efd0 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73 20  ne can use this 
1efe0 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20 73  text in an SQL s
1eff0 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c 6c  tatement as foll
1f000 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ows:.**.** <bloc
1f010 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1f020 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71   char *zSQL = sq
1f030 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49  lite3_mprintf("I
1f040 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1f050 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c 20   VALUES('%q')", 
1f060 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69  zText);.**  sqli
1f070 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53 51  te3_exec(db, zSQ
1f080 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20  L, 0, 0, 0);.** 
1f090 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a 53   sqlite3_free(zS
1f0a0 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  QL);.** </pre></
1f0b0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
1f0c0 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25 71  * Because the %q
1f0d0 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20 69   format string i
1f0e0 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27 27  s used, the '\''
1f0f0 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a 54   character in zT
1f100 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70 65  ext.** is escape
1f110 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67 65  d and the SQL ge
1f120 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66 6f  nerated is as fo
1f130 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
1f140 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
1f150 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  *  INSERT INTO t
1f160 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74  able1 VALUES('It
1f170 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  ''s a happy day!
1f180 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ').** </pre></bl
1f190 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1f1a0 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74 2e  This is correct.
1f1b0 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25 73    Had we used %s
1f1c0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c 20   instead of %q, 
1f1d0 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53 51  the generated SQ
1f1e0 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65 20  L.** would have 
1f1f0 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69 73  looked like this
1f200 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
1f210 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
1f220 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
1f230 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61 20   VALUES('It's a 
1f240 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a 2a  happy day!');.**
1f250 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1f260 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
1f270 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20 69  second example i
1f280 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78 20  s an SQL syntax 
1f290 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65 6e  error.  As a gen
1f2a0 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73 68  eral rule you sh
1f2b0 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20 75  ould.** always u
1f2c0 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f 66  se %q instead of
1f2d0 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74 69   %s when inserti
1f2e0 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20 73  ng text into a s
1f2f0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a 2a  tring literal..*
1f300 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f 70  *.** ^(The %Q op
1f310 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
1f320 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c 73  %q except it als
1f330 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71 75  o adds single qu
1f340 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20 74  otes around.** t
1f350 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68  he outside of th
1f360 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e 20  e total string. 
1f370 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69   Additionally, i
1f380 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
1f390 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d 65  in the.** argume
1f3a0 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55 4c  nt list is a NUL
1f3b0 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73 75  L pointer, %Q su
1f3c0 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74 65  bstitutes the te
1f3d0 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68 6f  xt "NULL" (witho
1f3e0 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75 6f  ut.** single quo
1f3f0 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f 72  tes).)^  So, for
1f400 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63 6f   example, one co
1f410 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c  uld say:.**.** <
1f420 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
1f430 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
1f440 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
1f450 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
1f460 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29 22  able VALUES(%Q)"
1f470 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71  , zText);.**  sq
1f480 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a  lite3_exec(db, z
1f490 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a  SQL, 0, 0, 0);.*
1f4a0 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  *  sqlite3_free(
1f4b0 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  zSQL);.** </pre>
1f4c0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
1f4d0 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62 6f  .** The code abo
1f4e0 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20 61  ve will render a
1f4f0 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74 61   correct SQL sta
1f500 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a 53  tement in the zS
1f510 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20 65  QL.** variable e
1f520 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78 74  ven if the zText
1f530 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20 4e   variable is a N
1f540 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
1f550 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66 6f  ** ^(The "%z" fo
1f560 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 20  rmatting option 
1f570 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22 20  works like "%s" 
1f580 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  but with the.** 
1f590 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61 66  addition that af
1f5a0 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20 68  ter the string h
1f5b0 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e 64  as been read and
1f5c0 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a 20   copied into.** 
1f5d0 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71 6c  the result, [sql
1f5e0 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73 20  ite3_free()] is 
1f5f0 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69 6e  called on the in
1f600 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a 2f  put string.)^.*/
1f610 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 68 61 72  .SQLITE_API char
1f620 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
1f630 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
1f640 2e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63  .);.SQLITE_API c
1f650 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70  har *sqlite3_vmp
1f660 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72  rintf(const char
1f670 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 53 51 4c  *, va_list);.SQL
1f680 49 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71  ITE_API char *sq
1f690 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
1f6a0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1f6b0 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 53 51 4c 49  har*, ...);.SQLI
1f6c0 54 45 5f 41 50 49 20 63 68 61 72 20 2a 73 71 6c  TE_API char *sql
1f6d0 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69  ite3_vsnprintf(i
1f6e0 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1f6f0 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a  har*, va_list);.
1f700 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1f710 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
1f720 6f 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a  on Subsystem.**.
1f730 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  ** The SQLite co
1f740 72 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68  re uses these th
1f750 72 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72  ree routines for
1f760 20 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a   all of its own.
1f770 2a 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f  ** internal memo
1f780 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65  ry allocation ne
1f790 65 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74  eds. "Core" in t
1f7a0 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74  he previous sent
1f7b0 65 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  ence.** does not
1f7c0 20 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69   include operati
1f7d0 6e 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66  ng-system specif
1f7e0 69 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  ic VFS implement
1f7f0 61 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57  ation.  The.** W
1f800 69 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20  indows VFS uses 
1f810 6e 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20  native malloc() 
1f820 61 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73  and free() for s
1f830 6f 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a  ome operations..
1f840 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1f850 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74  e3_malloc() rout
1f860 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ine returns a po
1f870 69 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b  inter to a block
1f880 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74  .** of memory at
1f890 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69   least N bytes i
1f8a0 6e 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20  n length, where 
1f8b0 4e 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74  N is the paramet
1f8c0 65 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  er..** ^If sqlit
1f8d0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75  e3_malloc() is u
1f8e0 6e 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20  nable to obtain 
1f8f0 73 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a  sufficient free.
1f900 2a 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65  ** memory, it re
1f910 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
1f920 6e 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70  nter.  ^If the p
1f930 61 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a  arameter N to.**
1f940 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28   sqlite3_malloc(
1f950 29 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67  ) is zero or neg
1f960 61 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74  ative then sqlit
1f970 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75  e3_malloc() retu
1f980 72 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f  rns.** a NULL po
1f990 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  inter..**.** ^Ca
1f9a0 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  lling sqlite3_fr
1f9b0 65 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e  ee() with a poin
1f9c0 74 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72  ter previously r
1f9d0 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
1f9e0 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f  lite3_malloc() o
1f9f0 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  r sqlite3_reallo
1fa00 63 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61  c() releases tha
1fa10 74 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74  t memory so.** t
1fa20 68 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20  hat it might be 
1fa30 72 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71  reused.  ^The sq
1fa40 6c 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75  lite3_free() rou
1fa50 74 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d  tine is.** a no-
1fa60 6f 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20  op if is called 
1fa70 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
1fa80 74 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20  ter.  Passing a 
1fa90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
1faa0 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  to sqlite3_free(
1fab0 29 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20  ) is harmless.  
1fac0 41 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65  After being free
1fad0 64 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f  d, memory.** sho
1fae0 75 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72  uld neither be r
1faf0 65 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e  ead nor written.
1fb00 20 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70    Even reading p
1fb10 72 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a  reviously freed.
1fb20 2a 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20  ** memory might 
1fb30 72 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d  result in a segm
1fb40 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f  entation fault o
1fb50 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65  r other severe e
1fb60 72 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20  rror..** Memory 
1fb70 63 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65  corruption, a se
1fb80 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74  gmentation fault
1fb90 2c 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72  , or other sever
1fba0 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74  e error.** might
1fbb0 20 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74   result if sqlit
1fbc0 65 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c  e3_free() is cal
1fbd0 6c 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  led with a non-N
1fbe0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ULL pointer that
1fbf0 0a 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61  .** was not obta
1fc00 69 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65  ined from sqlite
1fc10 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1fc20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e  lite3_realloc().
1fc30 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c  .**.** ^(The sql
1fc40 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
1fc50 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
1fc60 73 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a  s to resize a.**
1fc70 20 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c   prior memory al
1fc80 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61  location to be a
1fc90 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c  t least N bytes,
1fca0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a   where N is the.
1fcb0 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
1fcc0 74 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79  ter.  The memory
1fcd0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62   allocation to b
1fce0 65 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65  e resized is the
1fcf0 20 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65   first.** parame
1fd00 74 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20  ter.)^ ^ If the 
1fd10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
1fd20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1fd30 6f 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c  oc().** is a NUL
1fd40 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69  L pointer then i
1fd50 74 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69  ts behavior is i
1fd60 64 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c  dentical to call
1fd70 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d  ing.** sqlite3_m
1fd80 61 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e  alloc(N) where N
1fd90 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   is the second p
1fda0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1fdb0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1fdc0 2a 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64  * ^If the second
1fdd0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
1fde0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1fdf0 69 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65  is zero or.** ne
1fe00 67 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20  gative then the 
1fe10 62 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63  behavior is exac
1fe20 74 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20  tly the same as 
1fe30 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74  calling.** sqlit
1fe40 65 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65  e3_free(P) where
1fe50 20 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20   P is the first 
1fe60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1fe70 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
1fe80 2a 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c  ** ^sqlite3_real
1fe90 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20  loc() returns a 
1fea0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d  pointer to a mem
1feb0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
1fec0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20  * of at least N 
1fed0 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72  bytes in size or
1fee0 20 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69   NULL if suffici
1fef0 65 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e  ent memory is un
1ff00 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49  available..** ^I
1ff10 66 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20  f M is the size 
1ff20 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1ff30 6f 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69  ocation, then mi
1ff40 6e 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20  n(N,M) bytes.** 
1ff50 6f 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  of the prior all
1ff60 6f 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69  ocation are copi
1ff70 65 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69  ed into the begi
1ff80 6e 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20  nning of buffer 
1ff90 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73  returned.** by s
1ffa0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1ffb0 20 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61   and the prior a
1ffc0 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65  llocation is fre
1ffd0 65 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  ed..** ^If sqlit
1ffe0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74  e3_realloc() ret
1fff0 75 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  urns NULL, then 
20000 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  the prior alloca
20010 74 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66  tion.** is not f
20020 72 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  reed..**.** ^The
20030 20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64   memory returned
20040 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c   by sqlite3_mall
20050 6f 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  oc() and sqlite3
20060 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73  _realloc().** is
20070 20 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20   always aligned 
20080 74 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38  to at least an 8
20090 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20   byte boundary, 
200a0 6f 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74  or to a.** 4 byt
200b0 65 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68  e boundary if th
200c0 65 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45  e [SQLITE_4_BYTE
200d0 5f 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d  _ALIGNED_MALLOC]
200e0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
200f0 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e   option is used.
20100 0a 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65  .**.** In SQLite
20110 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61   version 3.5.0 a
20120 6e 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73  nd 3.5.1, it was
20130 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66   possible to def
20140 69 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54  ine.** the SQLIT
20150 45 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c  E_OMIT_MEMORY_AL
20160 4c 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77  LOCATION which w
20170 6f 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62  ould cause the b
20180 75 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65  uilt-in.** imple
20190 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65  mentation of the
201a0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  se routines to b
201b0 65 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74  e omitted.  That
201c0 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69   capability.** i
201d0 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76  s no longer prov
201e0 69 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c  ided.  Only buil
201f0 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  t-in memory allo
20200 63 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73  cators can be us
20210 65 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20  ed..**.** Prior 
20220 74 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  to SQLite versio
20230 6e 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69  n 3.7.10, the Wi
20240 6e 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61  ndows OS interfa
20250 63 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a  ce layer called.
20260 2a 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61  ** the system ma
20270 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
20280 29 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20  ) directly when 
20290 63 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69  converting.** fi
202a0 6c 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20  lenames between 
202b0 74 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69  the UTF-8 encodi
202c0 6e 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74  ng used by SQLit
202d0 65 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65  e.** and whateve
202e0 72 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64  r filename encod
202f0 69 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74  ing is used by t
20300 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69  he particular Wi
20310 6e 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c  ndows.** install
20320 61 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61  ation.  Memory a
20330 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
20340 20 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20   were detected, 
20350 62 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65  but.** they were
20360 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61   reported back a
20370 73 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s [SQLITE_CANTOP
20380 45 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54  EN] or.** [SQLIT
20390 45 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20  E_IOERR] rather 
203a0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  than [SQLITE_NOM
203b0 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70  EM]..**.** The p
203c0 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73  ointer arguments
203d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65   to [sqlite3_fre
203e0 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
203f0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
20400 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e  must be either N
20410 55 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e  ULL or else poin
20420 74 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72  ters obtained fr
20430 6f 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e  om a prior.** in
20440 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c  vocation of [sql
20450 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f  ite3_malloc()] o
20460 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  r [sqlite3_reall
20470 6f 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a  oc()] that have.
20480 2a 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20  ** not yet been 
20490 72 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  released..**.** 
204a0 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
204b0 6d 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72  must not read or
204c0 20 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20   write any part 
204d0 6f 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66  of.** a block of
204e0 20 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74   memory after it
204f0 20 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73   has been releas
20500 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
20510 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20  ite3_free()] or 
20520 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
20530 28 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  ()]..*/.SQLITE_A
20540 50 49 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  PI void *sqlite3
20550 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 53 51  _malloc(int);.SQ
20560 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73  LITE_API void *s
20570 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76  qlite3_realloc(v
20580 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 53 51 4c 49  oid*, int);.SQLI
20590 54 45 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69  TE_API void sqli
205a0 74 65 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b  te3_free(void*);
205b0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
205c0 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74  : Memory Allocat
205d0 6f 72 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a  or Statistics.**
205e0 0a 2a 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69  .** SQLite provi
205f0 64 65 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e  des these two in
20600 74 65 72 66 61 63 65 73 20 66 6f 72 20 72 65 70  terfaces for rep
20610 6f 72 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74  orting on the st
20620 61 74 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  atus.** of the [
20630 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
20640 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ], [sqlite3_free
20650 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
20660 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20  3_realloc()].** 
20670 72 6f 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20  routines, which 
20680 66 6f 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69  form the built-i
20690 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  n memory allocat
206a0 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a  ion subsystem..*
206b0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
206c0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
206d0 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  ] routine return
206e0 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
206f0 62 79 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  bytes.** of memo
20700 72 79 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74  ry currently out
20710 73 74 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63  standing (malloc
20720 65 64 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64  ed but not freed
20730 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  )..** ^The [sqli
20740 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
20750 61 74 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20  ater()] routine 
20760 72 65 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69  returns the maxi
20770 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20  mum.** value of 
20780 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
20790 75 73 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68  used()] since th
207a0 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  e high-water mar
207b0 6b 0a 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65  k.** was last re
207c0 73 65 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65  set.  ^The value
207d0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73  s returned by [s
207e0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
207f0 65 64 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  ed()] and.** [sq
20800 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
20810 68 77 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64  hwater()] includ
20820 65 20 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a  e any overhead.*
20830 2a 20 61 64 64 65 64 20 62 79 20 53 51 4c 69 74  * added by SQLit
20840 65 20 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65  e in its impleme
20850 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ntation of [sqli
20860 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a  te3_malloc()],.*
20870 2a 20 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65  * but not overhe
20880 61 64 20 61 64 64 65 64 20 62 79 20 74 68 65 20  ad added by the 
20890 61 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73  any underlying s
208a0 79 73 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a  ystem library.**
208b0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b   routines that [
208c0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
208d0 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a  ] may call..**.*
208e0 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69  * ^The memory hi
208f0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73  gh-water mark is
20900 20 72 65 73 65 74 20 74 6f 20 74 68 65 20 63 75   reset to the cu
20910 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a  rrent value of.*
20920 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  * [sqlite3_memor
20930 79 5f 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64  y_used()] if and
20940 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72   only if the par
20950 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71  ameter to.** [sq
20960 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
20970 68 77 61 74 65 72 28 29 5d 20 69 73 20 74 72 75  hwater()] is tru
20980 65 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72  e.  ^The value r
20990 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73  eturned.** by [s
209a0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
209b0 67 68 77 61 74 65 72 28 31 29 5d 20 69 73 20 74  ghwater(1)] is t
209c0 68 65 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61  he high-water ma
209d0 72 6b 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74  rk.** prior to t
209e0 68 65 20 72 65 73 65 74 2e 0a 2a 2f 0a 53 51 4c  he reset..*/.SQL
209f0 49 54 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f  ITE_API sqlite3_
20a00 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
20a10 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
20a20 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
20a30 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
20a40 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
20a50 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67  er(int resetFlag
20a60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
20a70 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f  EF: Pseudo-Rando
20a80 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74  m Number Generat
20a90 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  or.**.** SQLite 
20aa0 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d  contains a high-
20ab0 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72  quality pseudo-r
20ac0 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e  andom number gen
20ad0 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73  erator (PRNG) us
20ae0 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20  ed to.** select 
20af0 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20  random [ROWID | 
20b00 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73  ROWIDs] when ins
20b10 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72  erting new recor
20b20 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20  ds into a table 
20b30 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20  that.** already 
20b40 75 73 65 73 20 74 68 65 20 6c 61 72 67 65 73 74  uses the largest
20b50 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44   possible [ROWID
20b60 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69 73 20  ].  The PRNG is 
20b70 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a  also used for.**
20b80 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61   the build-in ra
20b90 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f  ndom() and rando
20ba0 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63  mblob() SQL func
20bb0 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74  tions.  This int
20bc0 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a  erface allows.**
20bd0 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f   applications to
20be0 20 61 63 63 65 73 73 20 74 68 65 20 73 61 6d 65   access the same
20bf0 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20   PRNG for other 
20c00 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20  purposes..**.** 
20c10 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20  ^A call to this 
20c20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e  routine stores N
20c30 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d   bytes of random
20c40 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72  ness into buffer
20c50 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66   P..**.** ^The f
20c60 69 72 73 74 20 74 69 6d 65 20 74 68 69 73 20 72  irst time this r
20c70 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65  outine is invoke
20c80 64 20 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e  d (either intern
20c90 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68  ally or by.** th
20ca0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74  e application) t
20cb0 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
20cc0 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
20cd0 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  ss obtained.** f
20ce0 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
20cf0 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
20d00 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
20d10 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
20d20 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65  ** ^On all subse
20d30 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
20d40 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61  s, the pseudo-ra
20d50 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65  ndomness is gene
20d60 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61  rated.** interna
20d70 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20  lly and without 
20d80 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20  recourse to the 
20d90 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52  [sqlite3_vfs] xR
20da0 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74  andomness.** met
20db0 68 6f 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  hod..*/.SQLITE_A
20dc0 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  PI void sqlite3_
20dd0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
20de0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
20df0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
20e00 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
20e10 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
20e20 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
20e30 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
20e40 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
20e50 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
20e60 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
20e70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20e80 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
20e90 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
20ea0 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
20eb0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
20ec0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
20ed0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
20ee0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
20ef0 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
20f00 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
20f10 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
20f20 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
20f30 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
20f40 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
20f50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
20f60 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
20f70 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
20f80 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
20f90 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
20fa0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
20fb0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
20fc0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
20fd0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
20fe0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
20ff0 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
21000 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
21010 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
21020 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
21030 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
21040 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
21050 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
21060 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
21070 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
21080 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
21090 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
210a0 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
210b0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
210c0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
210d0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
210e0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
210f0 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
21100 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
21110 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
21120 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
21130 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
21140 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
21150 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
21160 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
21170 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
21180 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
21190 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
211a0 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
211b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
211c0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
211d0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
211e0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
211f0 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
21200 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
21210 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
21220 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
21230 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
21240 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
21250 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
21260 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
21270 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
21280 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
21290 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
212a0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
212b0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
212c0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
212d0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
212e0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
212f0 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
21300 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
21310 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
21320 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
21330 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
21340 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
21350 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
21360 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
21370 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
21380 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
21390 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
213a0 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
213b0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
213c0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
213d0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
213e0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
213f0 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
21400 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
21410 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
21420 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
21430 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
21440 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
21450 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
21460 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
21470 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
21480 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
21490 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
214a0 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
214b0 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
214c0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
214d0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
214e0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
214f0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
21500 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
21510 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
21520 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
21530 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
21540 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
21550 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
21560 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
21570 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
21580 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
21590 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
215a0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
215b0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
215c0 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
215d0 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
215e0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
215f0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
21600 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
21610 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
21620 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
21630 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
21640 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
21650 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
21660 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
21670 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
21680 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
21690 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
216a0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
216b0 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
216c0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
216d0 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
216e0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
216f0 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
21700 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
21710 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
21720 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
21730 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
21740 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
21750 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
21760 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
21770 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
21780 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
21790 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
217a0 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
217b0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
217c0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
217d0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
217e0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
217f0 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
21800 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
21810 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
21820 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
21830 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
21840 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
21850 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
21860 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
21870 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
21880 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
21890 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
218a0 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
218b0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
218c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
218d0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
218e0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
218f0 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
21900 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
21910 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
21920 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
21930 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
21940 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
21950 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
21960 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
21970 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
21980 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
21990 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
219a0 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
219b0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
219c0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
219d0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
219e0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
219f0 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
21a00 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
21a10 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
21a20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
21a30 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
21a40 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
21a50 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
21a60 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
21a70 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
21a80 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
21a90 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
21aa0 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
21ab0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
21ac0 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
21ad0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
21ae0 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
21af0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
21b00 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
21b10 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
21b20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
21b30 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
21b40 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
21b50 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
21b60 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
21b70 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
21b80 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
21b90 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
21ba0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
21bb0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
21bc0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
21bd0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
21be0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
21bf0 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
21c00 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
21c10 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
21c20 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
21c30 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
21c40 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
21c50 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
21c60 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
21c70 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
21c80 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
21c90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
21ca0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
21cb0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
21cc0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
21cd0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
21ce0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21cf0 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
21d00 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
21d10 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
21d20 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
21d30 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
21d40 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
21d50 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
21d60 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
21d70 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
21d80 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
21d90 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
21da0 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
21db0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
21dc0 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
21dd0 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
21de0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
21df0 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
21e00 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
21e10 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
21e20 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
21e30 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
21e40 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
21e50 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
21e60 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
21e70 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
21e80 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
21e90 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
21ea0 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
21eb0 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
21ec0 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
21ed0 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
21ee0 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
21ef0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
21f00 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
21f10 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
21f20 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
21f30 6e 67 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41  nge..*/.SQLITE_A
21f40 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  PI int sqlite3_s
21f50 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20  et_authorizer(. 
21f60 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74   sqlite3*,.  int
21f70 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c   (*xAuth)(void*,
21f80 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  int,const char*,
21f90 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
21fa0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
21fb0 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55  ar*),.  void *pU
21fc0 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a  serData.);../*.*
21fd0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 68  * CAPI3REF: Auth
21fe0 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f  orizer Return Co
21ff0 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73  des.**.** The [s
22000 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
22010 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a  rizer | authoriz
22020 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  er callback func
22030 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65  tion] must.** re
22040 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c  turn either [SQL
22050 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f  ITE_OK] or one o
22060 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73  f these two cons
22070 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a  tants in order.*
22080 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69  * to signal SQLi
22090 74 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  te whether or no
220a0 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20  t the action is 
220b0 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20  permitted.  See 
220c0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
220d0 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c  set_authorizer |
220e0 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75   authorizer docu
220f0 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61  mentation] for a
22100 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66  dditional.** inf
22110 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
22120 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49 54 45  Note that SQLITE
22130 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20  _IGNORE is also 
22140 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c 49 54  used as a [SQLIT
22150 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 74  E_ROLLBACK | ret
22160 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f  urn code].** fro
22170 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
22180 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
22190 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
221a0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
221b0 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
221c0 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
221d0 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
221e0 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
221f0 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
22200 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
22210 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
22220 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
22230 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
22240 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
22250 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
22260 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
22270 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
22280 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
22290 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
222a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
222b0 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
222c0 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
222d0 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
222e0 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
222f0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
22300 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
22310 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
22320 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
22330 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
22340 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
22350 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
22360 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
22370 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
22380 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
22390 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
223a0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
223b0 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
223c0 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
223d0 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
223e0 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
223f0 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
22400 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
22410 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
22420 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
22430 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
22440 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
22450 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
22460 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
22470 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
22480 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
22490 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
224a0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
224b0 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
224c0 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
224d0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
224e0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
224f0 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
22500 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
22510 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
22520 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
22530 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
22540 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
22550 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
22560 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
22570 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
22580 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
22590 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
225a0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
225b0 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
225c0 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
225d0 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
225e0 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
225f0 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
22600 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22610 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
22620 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
22630 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
22640 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
22650 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
22660 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
22670 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
22680 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
22690 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
226a0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
226b0 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
226c0 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
226d0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
226e0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
226f0 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
22700 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
22710 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
22720 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
22730 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
22740 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
22750 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
22760 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22770 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
22780 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22790 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
227a0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
227b0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
227c0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
227d0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
227e0 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
227f0 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
22800 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
22810 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22820 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22830 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
22840 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
22850 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
22860 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
22870 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22880 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
22890 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
228a0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
228b0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
228c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
228d0 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
228e0 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
228f0 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
22900 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22910 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22920 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
22930 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
22940 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
22950 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22960 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22970 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
22980 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
22990 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
229a0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
229b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
229c0 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
229d0 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
229e0 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
229f0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
22a00 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
22a10 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
22a20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
22a30 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
22a40 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
22a50 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22a60 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
22a70 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
22a80 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
22a90 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
22aa0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
22ab0 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
22ac0 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
22ad0 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
22ae0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
22af0 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
22b00 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
22b10 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
22b20 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
22b30 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
22b40 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
22b50 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
22b60 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
22b70 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
22b80 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
22b90 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
22ba0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
22bb0 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
22bc0 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
22bd0 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
22be0 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
22bf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
22c00 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
22c10 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
22c20 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
22c30 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
22c40 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
22c50 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
22c60 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
22c70 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
22c80 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
22c90 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
22ca0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
22cb0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
22cc0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
22cd0 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
22ce0 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
22cf0 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
22d00 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
22d10 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
22d20 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
22d30 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
22d40 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
22d50 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
22d60 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
22d70 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
22d80 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
22d90 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
22da0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
22db0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
22dc0 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
22dd0 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
22de0 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
22df0 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
22e00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
22e10 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
22e20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
22e30 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
22e40 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
22e50 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
22e60 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
22e70 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
22e80 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
22e90 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
22ea0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
22eb0 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
22ec0 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
22ed0 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
22ee0 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
22ef0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
22f00 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
22f10 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
22f20 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
22f30 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
22f40 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
22f50 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
22f60 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
22f70 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
22f80 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
22f90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
22fa0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
22fb0 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
22fc0 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
22fd0 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
22fe0 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
22ff0 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
23000 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
23010 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
23020 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
23030 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
23040 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
23050 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
23060 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  r used */../*.**
23070 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69   CAPI3REF: Traci
23080 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67  ng And Profiling
23090 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
230a0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
230b0 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63  register callbac
230c0 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  k functions that
230d0 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72   can be used for
230e0 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20  .** tracing and 
230f0 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78  profiling the ex
23100 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73  ecution of SQL s
23110 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a  tatements..**.**
23120 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66   ^The callback f
23130 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72  unction register
23140 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72  ed by sqlite3_tr
23150 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ace() is invoked
23160 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74   at.** various t
23170 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c  imes when an SQL
23180 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65   statement is be
23190 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69  ing run by [sqli
231a0 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20  te3_step()]..** 
231b0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61  ^The sqlite3_tra
231c0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ce() callback is
231d0 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
231e0 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20  UTF-8 rendering 
231f0 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74  of the.** SQL st
23200 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20  atement text as 
23210 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69  the statement fi
23220 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75  rst begins execu
23230 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74  ting..** ^(Addit
23240 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72  ional sqlite3_tr
23250 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20  ace() callbacks 
23260 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61  might occur.** a
23270 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64  s each triggered
23280 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65   subprogram is e
23290 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c  ntered.  The cal
232a0 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67  lbacks for trigg
232b0 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61  ers.** contain a
232c0 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65   UTF-8 SQL comme
232d0 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69  nt that identifi
232e0 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29  es the trigger.)
232f0 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ^.**.** ^The cal
23300 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
23310 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
23320 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
23330 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
23340 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
23350 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
23360 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
23370 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
23380 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
23390 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
233a0 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
233b0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
233c0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
233d0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
233e0 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
233f0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
23400 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
23410 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
23420 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
23430 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
23440 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
23450 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
23460 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
23470 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
23480 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
23490 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
234a0 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
234b0 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
234c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
234d0 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
234e0 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
234f0 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
23500 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
23510 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
23520 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
23530 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
23540 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
23550 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
23560 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
23570 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
23580 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 53 51 4c  f SQLite..*/.SQL
23590 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
235a0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
235b0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
235c0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
235d0 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
235e0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
235f0 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c 20 76  E_EXPERIMENTAL v
23600 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70 72 6f  oid *sqlite3_pro
23610 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c 0a 20  file(sqlite3*,. 
23620 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69 6c 65    void(*xProfile
23630 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68  )(void*,const ch
23640 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69 6e 74  ar*,sqlite3_uint
23650 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a  64), void*);../*
23660 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 51 75  .** CAPI3REF: Qu
23670 65 72 79 20 50 72 6f 67 72 65 73 73 20 43 61 6c  ery Progress Cal
23680 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  lbacks.**.** ^Th
23690 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  e sqlite3_progre
236a0 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e 2c 58  ss_handler(D,N,X
236b0 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  ,P) interface ca
236c0 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62 61 63  uses the callbac
236d0 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 58 20  k.** function X 
236e0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 65  to be invoked pe
236f0 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72 69 6e  riodically durin
23700 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67 20 63  g long running c
23710 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  alls to.** [sqli
23720 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b 73 71  te3_exec()], [sq
23730 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 61 6e  lite3_step()] an
23740 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  d [sqlite3_get_t
23750 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a 20 64  able()] for.** d
23760 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
23770 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d 70 6c  on D.  An exampl
23780 65 20 75 73 65 20 66 6f 72 20 74 68 69 73 0a 2a  e use for this.*
23790 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
237a0 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75 70 64  o keep a GUI upd
237b0 61 74 65 64 20 64 75 72 69 6e 67 20 61 20 6c 61  ated during a la
237c0 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a  rge query..**.**
237d0 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
237e0 50 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  P is passed thro
237f0 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  ugh as the only 
23800 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
23810 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75   .** callback fu
23820 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68 65 20  nction X.  ^The 
23830 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73 20 74  parameter N is t
23840 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a 2a  he number of .**
23850 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e   [virtual machin
23860 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d 20  e instructions] 
23870 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61 74  that are evaluat
23880 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63 65  ed between succe
23890 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  ssive.** invocat
238a0 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c 6c  ions of the call
238b0 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  back X..**.** ^O
238c0 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70 72 6f  nly a single pro
238d0 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 6d 61  gress handler ma
238e0 79 20 62 65 20 64 65 66 69 6e 65 64 20 61 74 20  y be defined at 
238f0 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a 2a 20  one time per.** 
23900 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
23910 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67 20 61  tion]; setting a
23920 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20 68 61   new progress ha
23930 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20 74 68  ndler cancels th
23940 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e  e.** old one.  ^
23950 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65 74 65  Setting paramete
23960 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69 73 61  r X to NULL disa
23970 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72 65 73  bles the progres
23980 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54  s handler..** ^T
23990 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
239a0 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69 73 61  ler is also disa
239b0 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e 67 20  bled by setting 
239c0 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c 65 73  N to a value les
239d0 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a  s.** than 1..**.
239e0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f 67 72  ** ^If the progr
239f0 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  ess callback ret
23a00 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
23a10 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 0a  he operation is.
23a20 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64 2e 20  ** interrupted. 
23a30 20 54 68 69 73 20 66 65 61 74 75 72 65 20 63 61   This feature ca
23a40 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6d 70  n be used to imp
23a50 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43 61 6e  lement a.** "Can
23a60 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e 20 61  cel" button on a
23a70 20 47 55 49 20 70 72 6f 67 72 65 73 73 20 64 69   GUI progress di
23a80 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20  alog box..**.** 
23a90 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e  The progress han
23aa0 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75  dler callback mu
23ab0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
23ac0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
23ad0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
23ae0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
23af0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
23b00 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
23b10 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b  ..** Note that [
23b20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
23b30 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  v2()] and [sqlit
23b40 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20  e3_step()] both 
23b50 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20  modify their.** 
23b60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
23b70 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61  ions for the mea
23b80 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22  ning of "modify"
23b90 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72 61   in this paragra
23ba0 70 68 2e 0a 2a 2a 0a 2a 2f 0a 53 51 4c 49 54 45  ph..**.*/.SQLITE
23bb0 5f 41 50 49 20 76 6f 69 64 20 73 71 6c 69 74 65  _API void sqlite
23bc0 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c  3_progress_handl
23bd0 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74  er(sqlite3*, int
23be0 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c  , int(*)(void*),
23bf0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
23c00 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e  CAPI3REF: Openin
23c10 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73 65  g A New Database
23c20 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a   Connection.**.*
23c30 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
23c40 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74 65  s open an SQLite
23c50 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 61   database file a
23c60 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  s specified by t
23c70 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  he .** filename 
23c80 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66  argument. ^The f
23c90 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
23ca0 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
23cb0 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20  as UTF-8 for.** 
23cc0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
23cd0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
23ce0 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46 2d  v2() and as UTF-
23cf0 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76 65  16 in the native
23d00 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66   byte.** order f
23d10 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  or sqlite3_open1
23d20 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62 61  6(). ^(A [databa
23d30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
23d40 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c 79  andle is usually
23d50 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e 20  .** returned in 
23d60 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20 61  *ppDb, even if a
23d70 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
23d80 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70 74   The only except
23d90 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20 69  ion is that.** i
23da0 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  f SQLite is unab
23db0 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d  le to allocate m
23dc0 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68  emory to hold th
23dd0 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
23de0 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69  ct,.** a NULL wi
23df0 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69 6e  ll be written in
23e00 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61 64  to *ppDb instead
23e10 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   of a pointer to
23e20 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a   the [sqlite3].*
23e30 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66  * object.)^ ^(If
23e40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
23e50 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20   opened (and/or 
23e60 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73 73  created) success
23e70 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b  fully, then.** [
23e80 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65  SQLITE_OK] is re
23e90 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77 69  turned.  Otherwi
23ea0 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
23eb0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  e] is returned.)
23ec0 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ^ ^The.** [sqlit
23ed0 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72 20  e3_errmsg()] or 
23ee0 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 31  [sqlite3_errmsg1
23ef0 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63 61  6()] routines ca
23f00 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62 74  n be used to obt
23f10 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73  ain.** an Englis
23f20 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63 72  h language descr
23f30 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65 72  iption of the er
23f40 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20  ror following a 
23f50 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a  failure of any.*
23f60 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  * of the sqlite3
23f70 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65 73  _open() routines
23f80 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
23f90 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f  ault encoding fo
23fa0 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20 77  r the database w
23fb0 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66 0a  ill be UTF-8 if.
23fc0 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
23fd0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
23fe0 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  n_v2() is called
23ff0 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69   and.** UTF-16 i
24000 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
24010 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69 74  e order if sqlit
24020 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20 75  e3_open16() is u
24030 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68  sed..**.** Wheth
24040 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72  er or not an err
24050 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20 69  or occurs when i
24060 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65 73  t is opened, res
24070 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69  ources.** associ
24080 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
24090 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
240a0 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c  on] handle shoul
240b0 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62 79  d be released by
240c0 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20 74  .** passing it t
240d0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  o [sqlite3_close
240e0 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20 6e  ()] when it is n
240f0 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72 65  o longer require
24100 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  d..**.** The sql
24110 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
24120 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20 6c  nterface works l
24130 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ike sqlite3_open
24140 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61  ().** except tha
24150 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77 6f  t it accepts two
24160 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72 61   additional para
24170 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69 74  meters for addit
24180 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ional control.**
24190 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64 61   over the new da
241a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
241b0 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73 20  n.  ^(The flags 
241c0 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
241d0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
241e0 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f  ) can take one o
241f0 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69  f.** the followi
24200 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73 2c  ng three values,
24210 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
24220 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ined with the .*
24230 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e  * [SQLITE_OPEN_N
24240 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  OMUTEX], [SQLITE
24250 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
24260 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  , [SQLITE_OPEN_S
24270 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20  HAREDCACHE],.** 
24280 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49  [SQLITE_OPEN_PRI
24290 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f  VATECACHE], and/
242a0 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  or [SQLITE_OPEN_
242b0 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a  URI] flags:)^.**
242c0 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64  .** <dl>.** ^(<d
242d0 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52  t>[SQLITE_OPEN_R
242e0 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a  EADONLY]</dt>.**
242f0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
24300 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20 72  e is opened in r
24310 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20  ead-only mode.  
24320 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
24330 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65  does not.** alre
24340 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65 72  ady exist, an er
24350 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ror is returned.
24360 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
24370 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  <dt>[SQLITE_OPEN
24380 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e  _READWRITE]</dt>
24390 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
243a0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
243b0 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
243c0 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69 62  riting if possib
243d0 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a  le, or reading.*
243e0 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66 69  * only if the fi
243f0 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f 74  le is write prot
24400 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70 65  ected by the ope
24410 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20  rating system.  
24420 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61 73  In either.** cas
24430 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d  e the database m
24440 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69 73  ust already exis
24450 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20  t, otherwise an 
24460 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
24470 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  d.</dd>)^.**.** 
24480 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50  ^(<dt>[SQLITE_OP
24490 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c 20  EN_READWRITE] | 
244a0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
244b0 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATE]</dt>.** <dd
244c0 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73  >The database is
244d0 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
244e0 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 2c  ing and writing,
244f0 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64 20   and is created 
24500 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f  if.** it does no
24510 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2e  t already exist.
24520 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65 68   This is the beh
24530 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61 6c  avior that is al
24540 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a  ways used for.**
24550 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
24560 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
24570 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20  16().</dd>)^.** 
24580 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  </dl>.**.** If t
24590 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
245a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
245b0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65  _v2() is not one
245c0 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69   of the.** combi
245d0 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62  nations shown ab
245e0 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63  ove optionally c
245f0 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74 68  ombined with oth
24600 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  er.** [SQLITE_OP
24610 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51  EN_READONLY | SQ
24620 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73  LITE_OPEN_* bits
24630 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62 65  ].** then the be
24640 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
24650 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ned..**.** ^If t
24660 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
24670 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73  NOMUTEX] flag is
24680 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20 64   set, then the d
24690 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
246a0 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74  on.** opens in t
246b0 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 20  he multi-thread 
246c0 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
246d0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20   as long as the 
246e0 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a  single-thread.**
246f0 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62 65   mode has not be
24700 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69 6c  en set at compil
24710 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
24720 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a  time.  ^If the.*
24730 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46  * [SQLITE_OPEN_F
24740 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  ULLMUTEX] flag i
24750 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20 64  s set then the d
24760 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
24770 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74  on opens.** in t
24780 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
24790 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75  hreading mode] u
247a0 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68 72  nless single-thr
247b0 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76 69  ead was.** previ
247c0 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20 61  ously selected a
247d0 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
247e0 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a  r start-time..**
247f0 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
24800 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d 20  EN_SHAREDCACHE] 
24810 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20  flag causes the 
24820 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24830 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69  ion to be.** eli
24840 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73 68  gible to use [sh
24850 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d  ared cache mode]
24860 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  , regardless of 
24870 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
24880 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20 69  hared.** cache i
24890 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67 20  s enabled using 
248a0 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f  [sqlite3_enable_
248b0 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d 2e  shared_cache()].
248c0 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54    ^The.** [SQLIT
248d0 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
248e0 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65 73  CHE] flag causes
248f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
24900 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a  nnection to not.
24910 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20 69  ** participate i
24920 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65 20  n [shared cache 
24930 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69 74  mode] even if it
24940 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a   is enabled..**.
24950 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70  ** ^The fourth p
24960 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
24970 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
24980 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
24990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  .** [sqlite3_vfs
249a0 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64 65  ] object that de
249b0 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61 74  fines the operat
249c0 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72  ing system inter
249d0 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68 65  face that.** the
249e0 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
249f0 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20  nnection should 
24a00 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66 6f  use.  ^If the fo
24a10 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
24a20 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
24a30 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65 66  ter then the def
24a40 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66  ault [sqlite3_vf
24a50 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  s] object is use
24a60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
24a70 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d   filename is ":m
24a80 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61 20  emory:", then a 
24a90 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61  private, tempora
24aa0 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74  ry in-memory dat
24ab0 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65 61  abase.** is crea
24ac0 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e  ted for the conn
24ad0 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69  ection.  ^This i
24ae0 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
24af0 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77 68  e will vanish wh
24b00 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  en.** the databa
24b10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
24b20 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72 65   closed.  Future
24b30 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
24b40 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b  ite might.** mak
24b50 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69 6f  e use of additio
24b60 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c 65  nal special file
24b70 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69 6e  names that begin
24b80 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63 68   with the ":" ch
24b90 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69  aracter..** It i
24ba0 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
24bb0 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62 61  at when a databa
24bc0 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74 75  se filename actu
24bd0 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e 20  ally does begin 
24be0 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68  with.** a ":" ch
24bf0 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f 75  aracter you shou
24c00 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66 69  ld prefix the fi
24c10 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70 61  lename with a pa
24c20 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a 2a  thname such as.*
24c30 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20  * "./" to avoid 
24c40 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a  ambiguity..**.**
24c50 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
24c60 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73 74  e is an empty st
24c70 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72 69  ring, then a pri
24c80 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a  vate, temporary.
24c90 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62  ** on-disk datab
24ca0 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65 61  ase will be crea
24cb0 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69 76  ted.  ^This priv
24cc0 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69 6c  ate database wil
24cd0 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  l be.** automati
24ce0 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61 73  cally deleted as
24cf0 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61 74   soon as the dat
24d00 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
24d10 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a   is closed..**.*
24d20 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  * [[URI filename
24d30 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65  s in sqlite3_ope
24d40 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69  n()]] <h3>URI Fi
24d50 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a  lenames</h3>.**.
24d60 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c 65  ** ^If [URI file
24d70 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74 61  name] interpreta
24d80 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c  tion is enabled,
24d90 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61 6d   and the filenam
24da0 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65  e argument.** be
24db0 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65 3a  gins with "file:
24dc0 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c 65  ", then the file
24dd0 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72 65  name is interpre
24de0 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e 55  ted as a URI. ^U
24df0 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  RI.** filename i
24e00 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
24e10 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20   enabled if the 
24e20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
24e30 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74  ] flag is.** set
24e40 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61   in the fourth a
24e50 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
24e60 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72  e3_open_v2(), or
24e70 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62 65   if it has.** be
24e80 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61  en enabled globa
24e90 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b 53  lly using the [S
24ea0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49  QLITE_CONFIG_URI
24eb0 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74 68  ] option with th
24ec0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
24ed0 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f  nfig()] method o
24ee0 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54 45  r by the [SQLITE
24ef0 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c  _USE_URI] compil
24f00 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a  e-time option..*
24f10 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20 76  * As of SQLite v
24f20 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52  ersion 3.7.7, UR
24f30 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72  I filename inter
24f40 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75 72  pretation is tur
24f50 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65  ned off.** by de
24f60 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75 72  fault, but futur
24f70 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
24f80 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62 6c  Lite might enabl
24f90 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a  e URI filename.*
24fa0 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e  * interpretation
24fb0 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53 65   by default.  Se
24fc0 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65  e "[URI filename
24fd0 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  s]" for addition
24fe0 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  al.** informatio
24ff0 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c  n..**.** URI fil
25000 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73 65  enames are parse
25010 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 52  d according to R
25020 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68 65  FC 3986. ^If the
25030 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e   URI contains an
25040 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20 74  .** authority, t
25050 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20 65  hen it must be e
25060 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20 73  ither an empty s
25070 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74 72  tring or the str
25080 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f  ing .** "localho
25090 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75 74  st". ^If the aut
250a0 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61 6e  hority is not an
250b0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
250c0 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e   "localhost", an
250d0 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72 65   .** error is re
250e0 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63 61  turned to the ca
250f0 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67 6d  ller. ^The fragm
25100 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ent component of
25110 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70   a URI, if .** p
25120 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72  resent, is ignor
25130 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ed..**.** ^SQLit
25140 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68 20  e uses the path 
25150 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65  component of the
25160 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d 65   URI as the name
25170 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69 6c   of the disk fil
25180 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74 61  e.** which conta
25190 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ins the database
251a0 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20 62  . ^If the path b
251b0 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f 27  egins with a '/'
251c0 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20   character, .** 
251d0 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65 72  then it is inter
251e0 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62 73  preted as an abs
251f0 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66 20  olute path. ^If 
25200 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e 6f  the path does no
25210 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68  t begin .** with
25220 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20   a '/' (meaning 
25230 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
25240 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d  ty section is om
25250 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20 55  itted from the U
25260 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  RI).** then the 
25270 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72 65  path is interpre
25280 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69 76  ted as a relativ
25290 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20  e path. .** ^On 
252a0 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69 72  windows, the fir
252b0 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20  st component of 
252c0 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68  an absolute path
252d0 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65 20   .** is a drive 
252e0 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28 65  specification (e
252f0 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a  .g. "C:")..**.**
25300 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65 72   [[core URI quer
25310 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a  y parameters]].*
25320 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
25330 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
25340 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
25350 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
25360 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
25370 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
25380 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
25390 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46 53  VFS | custom VFS
253a0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d   implementation]
253b0 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65  ..** SQLite inte
253c0 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f  rprets the follo
253d0 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72 79  wing three query
253e0 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a   parameters:.**.
253f0 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69  ** <ul>.**   <li
25400 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54  > <b>vfs</b>: ^T
25410 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65 74  he "vfs" paramet
25420 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20 74  er may be used t
25430 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e 61  o specify the na
25440 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56  me of.**     a V
25450 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20 70  FS object that p
25460 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65 72  rovides the oper
25470 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74  ating system int
25480 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f 75  erface that shou
25490 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73 65  ld.**     be use
254a0 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  d to access the 
254b0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f 6e  database file on
254c0 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73 20   disk. ^If this 
254d0 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
254e0 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74 79  .**     an empty
254f0 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66 61   string the defa
25500 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20 69  ult VFS object i
25510 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66 79  s used. ^Specify
25520 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a  ing an unknown.*
25530 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e 20  *     VFS is an 
25540 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74  error. ^If sqlit
25550 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
25560 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66 73  used and the vfs
25570 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20   option is.**   
25580 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e 20    present, then 
25590 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69 65  the VFS specifie
255a0 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e 20  d by the option 
255b0 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63 65  takes precedence
255c0 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68 65   over.**     the
255d0 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
255e0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
255f0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
25600 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a  _open_v2()..**.*
25610 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65  *   <li> <b>mode
25620 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65  </b>: ^(The mode
25630 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
25640 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
25650 22 72 6f 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20  "ro", "rw",.**  
25660 20 20 20 22 72 77 63 22 2c 20 6f 72 20 22 6d 65     "rwc", or "me
25670 6d 6f 72 79 22 2e 20 41 74 74 65 6d 70 74 69 6e  mory". Attemptin
25680 67 20 74 6f 20 73 65 74 20 69 74 20 74 6f 20 61  g to set it to a
25690 6e 79 20 6f 74 68 65 72 20 76 61 6c 75 65 20 69  ny other value i
256a0 73 0a 2a 2a 20 20 20 20 20 61 6e 20 65 72 72 6f  s.**     an erro
256b0 72 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66  r)^. .**     ^If
256c0 20 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69   "ro" is specifi
256d0 65 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74  ed, then the dat
256e0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
256f0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a  for read-only .*
25700 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75  *     access, ju
25710 73 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51  st as if the [SQ
25720 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
25730 4c 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65  LY] flag had bee
25740 6e 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a  n set in the .**
25750 20 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d       third argum
25760 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
25770 70 65 6e 5f 76 32 28 29 2e 20 5e 49 66 20 74 68  pen_v2(). ^If th
25780 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73  e mode option is
25790 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20   set to .**     
257a0 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65 20 64  "rw", then the d
257b0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
257c0 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69 74 65  d for read-write
257d0 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61 74 65   (but not create
257e0 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65 73 73  ) .**     access
257f0 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45 5f 4f  , as if SQLITE_O
25800 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 28 62  PEN_READWRITE (b
25810 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50  ut not SQLITE_OP
25820 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64 20 0a  EN_CREATE) had .
25830 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65 74 2e  **     been set.
25840 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20 69 73   ^Value "rwc" is
25850 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
25860 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20  etting both .** 
25870 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
25880 52 45 41 44 57 52 49 54 45 20 61 6e 64 20 53 51  READWRITE and SQ
25890 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
258a0 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  .  ^If the mode 
258b0 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20  option is.**    
258c0 20 73 65 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22   set to "memory"
258d0 20 74 68 65 6e 20 61 20 70 75 72 65 20 5b 69 6e   then a pure [in
258e0 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65  -memory database
258f0 5d 20 74 68 61 74 20 6e 65 76 65 72 20 72 65 61  ] that never rea
25900 64 73 0a 2a 2a 20 20 20 20 20 6f 72 20 77 72 69  ds.**     or wri
25910 74 65 73 20 66 72 6f 6d 20 64 69 73 6b 20 69 73  tes from disk is
25920 20 75 73 65 64 2e 20 5e 49 74 20 69 73 20 61 6e   used. ^It is an
25930 20 65 72 72 6f 72 20 74 6f 20 73 70 65 63 69 66   error to specif
25940 79 20 61 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a  y a value for.**
25950 20 20 20 20 20 74 68 65 20 6d 6f 64 65 20 70 61       the mode pa
25960 72 61 6d 65 74 65 72 20 74 68 61 74 20 69 73 20  rameter that is 
25970 6c 65 73 73 20 72 65 73 74 72 69 63 74 69 76 65  less restrictive
25980 20 74 68 61 6e 20 74 68 61 74 20 73 70 65 63 69   than that speci
25990 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 74  fied by.**     t
259a0 68 65 20 66 6c 61 67 73 20 70 61 73 73 65 64 20  he flags passed 
259b0 69 6e 20 74 68 65 20 74 68 69 72 64 20 70 61 72  in the third par
259c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
259d0 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
259e0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
259f0 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
25a00 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
25a10 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
25a20 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
25a30 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
25a40 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
25a50 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
25a60 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
25a70 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
25a80 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
25a90 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
25aa0 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
25ab0 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
25ac0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
25ad0 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
25ae0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
25af0 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
25b00 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
25b10 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
25b20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
25b30 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
25b40 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
25b50 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
25b60 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
25b70 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
25b80 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
25b90 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
25ba0 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
25bb0 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
25bc0 69 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62  iour requested b
25bd0 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
25be0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
25bf0 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
25c00 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
25c10 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f  ACHE flag..** </
25c20 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
25c30 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
25c40 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
25c50 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
25c60 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
25c70 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
25c80 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
25c90 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
25ca0 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
25cb0 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
25cc0 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
25cd0 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
25ce0 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
25cf0 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
25d00 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
25d10 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
25d20 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
25d30 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
25d40 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
25d50 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
25d60 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
25d70 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
25d80 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
25d90 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
25da0 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
25db0 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
25dc0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
25dd0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
25de0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
25df0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
25e00 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
25e10 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
25e20 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
25e30 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
25e40 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
25e50 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
25e60 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
25e70 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
25e80 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
25e90 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
25ea0 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
25eb0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
25ec0 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
25ed0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
25ee0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
25ef0 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
25f00 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
25f10 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
25f20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
25f30 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
25f40 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
25f50 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
25f60 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
25f70 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
25f80 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
25f90 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
25fa0 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
25fb0 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
25fc0 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
25fd0 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
25fe0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
25ff0 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
26000 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
26010 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
26020 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
26030 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
26040 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
26050 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
26060 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
26070 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
26080 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
26090 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
260a0 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
260b0 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
260c0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
260d0 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
260e0 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
260f0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
26100 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
26110 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
26120 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
26130 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
26140 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
26150 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
26160 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
26170 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
26180 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
26190 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
261a0 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
261b0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
261c0 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
261d0 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f  a.db?vfs=unix-no
261e0 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  lock <td>.**    
261f0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
26200 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
26210 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
26220 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
26230 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e  nolock"..** <tr>
26240 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
26250 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
26260 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
26270 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
26280 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
26290 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
262a0 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
262b0 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
262c0 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
262d0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
262e0 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
262f0 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
26300 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
26310 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
26320 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
26330 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
26340 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
26350 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
26360 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
26370 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
26380 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
26390 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
263a0 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
263b0 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
263c0 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
263d0 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
263e0 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
263f0 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
26400 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
26410 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
26420 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
26430 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
26440 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
26450 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
26460 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
26470 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
26480 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
26490 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
264a0 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
264b0 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
264c0 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
264d0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
264e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
264f0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
26500 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
26510 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
26520 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
26530 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
26540 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
26550 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
26560 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
26570 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
26580 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
26590 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
265a0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
265b0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
265c0 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
265d0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
265e0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
265f0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
26600 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
26610 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
26620 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a  e3_open_v2()..**
26630 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
26640 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
26650 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
26660 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
26670 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
26680 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
26690 6e 67 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ng sqlite3_open(
266a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
266b0 6e 5f 76 32 28 29 2e 20 20 4f 74 68 65 72 77 69  n_v2().  Otherwi
266c0 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
266d0 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
266e0 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
266f0 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
26700 6d 61 79 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20  may fail..**.** 
26710 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
26720 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
26730 79 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  y].*/.SQLITE_API
26740 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
26750 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
26760 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
26770 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
26780 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
26790 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
267a0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
267b0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
267c0 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  */.);.SQLITE_API
267d0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65   int sqlite3_ope
267e0 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76 6f 69  n16(.  const voi
267f0 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  d *filename,   /
26800 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
26810 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a 2f 0a  ame (UTF-16) */.
26820 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62    sqlite3 **ppDb
26830 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
26840 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64  : SQLite db hand
26850 6c 65 20 2a 2f 0a 29 3b 0a 53 51 4c 49 54 45 5f  le */.);.SQLITE_
26860 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
26870 6f 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74  open_v2(.  const
26880 20 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c   char *filename,
26890 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
268a0 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20  ilename (UTF-8) 
268b0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70  */.  sqlite3 **p
268c0 70 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20  pDb,         /* 
268d0 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68  OUT: SQLite db h
268e0 61 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66  andle */.  int f
268f0 6c 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20  lags,           
26900 20 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20     /* Flags */. 
26910 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66   const char *zVf
26920 73 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65  s        /* Name
26930 20 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74   of VFS module t
26940 6f 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a  o use */.);../*.
26950 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
26960 61 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55  ain Values For U
26970 52 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a  RI Parameters.**
26980 0a 2a 2a 20 54 68 65 73 65 20 61 72 65 20 75 74  .** These are ut
26990 69 6c 69 74 79 20 72 6f 75 74 69 6e 65 73 2c 20  ility routines, 
269a0 75 73 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d  useful to VFS im
269b0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74  plementations, t
269c0 68 61 74 20 63 68 65 63 6b 0a 2a 2a 20 74 6f 20  hat check.** to 
269d0 73 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73  see if a databas
269e0 65 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49  e file was a URI
269f0 20 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20   that contained 
26a00 61 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79  a specific query
26a10 20 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20   .** parameter, 
26a20 61 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e  and if so obtain
26a30 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74  s the value of t
26a40 68 61 74 20 71 75 65 72 79 20 70 61 72 61 6d 65  hat query parame
26a50 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20  ter..**.** If F 
26a60 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  is the database 
26a70 66 69 6c 65 6e 61 6d 65 20 70 6f 69 6e 74 65 72  filename pointer
26a80 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
26a90 20 78 4f 70 65 6e 28 29 20 6d 65 74 68 6f 64 20   xOpen() method 
26aa0 6f 66 20 0a 2a 2a 20 61 20 56 46 53 20 69 6d 70  of .** a VFS imp
26ab0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 65 6e  lementation when
26ac0 20 74 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d   the flags param
26ad0 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 28 29 20  eter to xOpen() 
26ae0 68 61 73 20 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d  has one or .** m
26af0 6f 72 65 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  ore of the [SQLI
26b00 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 6f 72 20  TE_OPEN_URI] or 
26b10 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
26b20 4e 5f 44 42 5d 20 62 69 74 73 20 73 65 74 20 61  N_DB] bits set a
26b30 6e 64 0a 2a 2a 20 50 20 69 73 20 74 68 65 20 6e  nd.** P is the n
26b40 61 6d 65 20 6f 66 20 74 68 65 20 71 75 65 72 79  ame of the query
26b50 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
26b60 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
26b70 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72  parameter(F,P) r
26b80 65 74 75 72 6e 73 20 74 68 65 20 76 61 6c 75 65  eturns the value
26b90 20 6f 66 20 74 68 65 20 50 0a 2a 2a 20 70 61 72   of the P.** par
26ba0 61 6d 65 74 65 72 20 69 66 20 69 74 20 65 78 69  ameter if it exi
26bb0 73 74 73 20 6f 72 20 61 20 4e 55 4c 4c 20 70 6f  sts or a NULL po
26bc0 69 6e 74 65 72 20 69 66 20 50 20 64 6f 65 73 20  inter if P does 
26bd0 6e 6f 74 20 61 70 70 65 61 72 20 61 73 20 61 20  not appear as a 
26be0 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
26bf0 74 65 72 20 6f 6e 20 46 2e 20 20 49 66 20 50 20  ter on F.  If P 
26c00 69 73 20 61 20 71 75 65 72 79 20 70 61 72 61 6d  is a query param
26c10 65 74 65 72 20 6f 66 20 46 0a 2a 2a 20 68 61 73  eter of F.** has
26c20 20 6e 6f 20 65 78 70 6c 69 63 69 74 20 76 61 6c   no explicit val
26c30 75 65 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ue, then sqlite3
26c40 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 46  _uri_parameter(F
26c50 2c 50 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  ,P) returns.** a
26c60 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 65   pointer to an e
26c70 6d 70 74 79 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a  mpty string..**.
26c80 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
26c90 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
26ca0 29 20 72 6f 75 74 69 6e 65 20 61 73 73 75 6d 65  ) routine assume
26cb0 73 20 74 68 61 74 20 50 20 69 73 20 61 20 62 6f  s that P is a bo
26cc0 6f 6c 65 61 6e 0a 2a 2a 20 70 61 72 61 6d 65 74  olean.** paramet
26cd0 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
26ce0 72 75 65 20 28 31 29 20 6f 72 20 66 61 6c 73 65  rue (1) or false
26cf0 20 28 30 29 20 61 63 63 6f 72 64 69 6e 67 20 74   (0) according t
26d00 6f 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 6f  o the value.** o
26d10 66 20 50 2e 20 20 54 68 65 20 73 71 6c 69 74 65  f P.  The sqlite
26d20 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c  3_uri_boolean(F,
26d30 50 2c 42 29 20 72 6f 75 74 69 6e 65 20 72 65 74  P,B) routine ret
26d40 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 69 66  urns true (1) if
26d50 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66   the.** value of
26d60 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
26d70 20 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 79 65   P is one of "ye
26d80 73 22 2c 20 22 74 72 75 65 22 2c 20 6f 72 20 22  s", "true", or "
26d90 6f 6e 22 20 69 6e 20 61 6e 79 0a 2a 2a 20 63 61  on" in any.** ca
26da0 73 65 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c  se or if the val
26db0 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
26dc0 20 6e 6f 6e 2d 7a 65 72 6f 20 6e 75 6d 62 65 72   non-zero number
26dd0 2e 20 20 54 68 65 20 0a 2a 2a 20 73 71 6c 69 74  .  The .** sqlit
26de0 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
26df0 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65 73 20 72  ,P,B) routines r
26e00 65 74 75 72 6e 73 20 66 61 6c 73 65 20 28 30 29  eturns false (0)
26e10 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   if the value of
26e20 0a 2a 2a 20 71 75 65 72 79 20 70 61 72 61 6d 65  .** query parame
26e30 74 65 72 20 50 20 69 73 20 6f 6e 65 20 6f 66 20  ter P is one of 
26e40 22 6e 6f 22 2c 20 22 66 61 6c 73 65 22 2c 20 6f  "no", "false", o
26e50 72 20 22 6f 66 66 22 20 69 6e 20 61 6e 79 20 63  r "off" in any c
26e60 61 73 65 20 6f 72 0a 2a 2a 20 69 66 20 74 68 65  ase or.** if the
26e70 20 76 61 6c 75 65 20 62 65 67 69 6e 73 20 77 69   value begins wi
26e80 74 68 20 61 20 6e 75 6d 65 72 69 63 20 7a 65 72  th a numeric zer
26e90 6f 2e 20 20 49 66 20 50 20 69 73 20 6e 6f 74 20  o.  If P is not 
26ea0 61 20 71 75 65 72 79 0a 2a 2a 20 70 61 72 61 6d  a query.** param
26eb0 65 74 65 72 20 6f 6e 20 46 20 6f 72 20 69 66 20  eter on F or if 
26ec0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
26ed0 73 20 64 6f 65 73 20 6e 6f 74 20 6d 61 74 63 68  s does not match
26ee0 20 61 6e 79 20 6f 66 20 74 68 65 0a 2a 2a 20 61   any of the.** a
26ef0 62 6f 76 65 2c 20 74 68 65 6e 20 73 71 6c 69 74  bove, then sqlit
26f00 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
26f10 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 28 42  ,P,B) returns (B
26f20 21 3d 30 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  !=0)..**.** The 
26f30 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
26f40 34 28 46 2c 50 2c 44 29 20 72 6f 75 74 69 6e 65  4(F,P,D) routine
26f50 20 63 6f 6e 76 65 72 74 73 20 74 68 65 20 76 61   converts the va
26f60 6c 75 65 20 6f 66 20 50 20 69 6e 74 6f 20 61 0a  lue of P into a.
26f70 2a 2a 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  ** 64-bit signed
26f80 20 69 6e 74 65 67 65 72 20 61 6e 64 20 72 65 74   integer and ret
26f90 75 72 6e 73 20 74 68 61 74 20 69 6e 74 65 67 65  urns that intege
26fa0 72 2c 20 6f 72 20 44 20 69 66 20 50 20 64 6f 65  r, or D if P doe
26fb0 73 20 6e 6f 74 0a 2a 2a 20 65 78 69 73 74 2e 20  s not.** exist. 
26fc0 20 49 66 20 74 68 65 20 76 61 6c 75 65 20 6f 66   If the value of
26fd0 20 50 20 69 73 20 73 6f 6d 65 74 68 69 6e 67 20   P is something 
26fe0 6f 74 68 65 72 20 74 68 61 6e 20 61 6e 20 69 6e  other than an in
26ff0 74 65 67 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a  teger, then.** z
27000 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
27010 0a 2a 2a 20 0a 2a 2a 20 49 66 20 46 20 69 73 20  .** .** If F is 
27020 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20  a NULL pointer, 
27030 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
27040 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
27050 72 65 74 75 72 6e 73 20 4e 55 4c 4c 20 61 6e 64  returns NULL and
27060 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
27070 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
27080 65 74 75 72 6e 73 20 42 2e 20 20 49 66 20 46 20  eturns B.  If F 
27090 69 73 20 6e 6f 74 20 61 20 4e 55 4c 4c 20 70 6f  is not a NULL po
270a0 69 6e 74 65 72 20 61 6e 64 0a 2a 2a 20 69 73 20  inter and.** is 
270b0 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
270c0 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 70 6f 69  ile pathname poi
270d0 6e 74 65 72 20 74 68 61 74 20 53 51 4c 69 74 65  nter that SQLite
270e0 20 70 61 73 73 65 64 20 69 6e 74 6f 20 74 68 65   passed into the
270f0 20 78 4f 70 65 6e 0a 2a 2a 20 56 46 53 20 6d 65   xOpen.** VFS me
27100 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 65 20 62  thod, then the b
27110 65 68 61 76 69 6f 72 20 6f 66 20 74 68 69 73 20  ehavior of this 
27120 72 6f 75 74 69 6e 65 20 69 73 20 75 6e 64 65 66  routine is undef
27130 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c  ined and probabl
27140 79 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65  y.** undesirable
27150 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20  ..*/.SQLITE_API 
27160 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
27170 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
27180 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  r(const char *zF
27190 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63  ilename, const c
271a0 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 53 51  har *zParam);.SQ
271b0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
271c0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
271d0 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
271e0 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  le, const char *
271f0 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65 66  zParam, int bDef
27200 61 75 6c 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ault);.SQLITE_AP
27210 49 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  I sqlite3_int64 
27220 73 71 6c 69 74 65 33 5f 75 72 69 5f 69 6e 74 36  sqlite3_uri_int6
27230 34 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 63  4(const char*, c
27240 6f 6e 73 74 20 63 68 61 72 2a 2c 20 73 71 6c 69  onst char*, sqli
27250 74 65 33 5f 69 6e 74 36 34 29 3b 0a 0a 0a 2f 2a  te3_int64);.../*
27260 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72  .** CAPI3REF: Er
27270 72 6f 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65  ror Codes And Me
27280 73 73 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ssages.**.** ^Th
27290 65 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  e sqlite3_errcod
272a0 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  e() interface re
272b0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69  turns the numeri
272c0 63 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20  c [result code] 
272d0 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  or.** [extended 
272e0 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72  result code] for
272f0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
27300 20 66 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f   failed sqlite3_
27310 2a 20 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73  * API call.** as
27320 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
27330 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27340 74 69 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f  tion]. If a prio
27350 72 20 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65  r API call faile
27360 64 0a 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73  d.** but the mos
27370 74 20 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c  t recent API cal
27380 6c 20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65  l succeeded, the
27390 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
273a0 6f 6d 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72  om.** sqlite3_er
273b0 72 63 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66  rcode() is undef
273c0 69 6e 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  ined.  ^The sqli
273d0 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
273e0 63 6f 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66  code().** interf
273f0 61 63 65 20 69 73 20 74 68 65 20 73 61 6d 65 20  ace is the same 
27400 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
27410 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 74 68  lways returns th
27420 65 20 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20  e .** [extended 
27430 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65  result code] eve
27440 6e 20 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20  n when extended 
27450 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
27460 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a  .** disabled..**
27470 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
27480 5f 65 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71  _errmsg() and sq
27490 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
274a0 20 72 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d   return English-
274b0 6c 61 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74  language.** text
274c0 20 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20   that describes 
274d0 74 68 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69  the error, as ei
274e0 74 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54  ther UTF-8 or UT
274f0 46 2d 31 36 20 72 65 73 70 65 63 74 69 76 65 6c  F-16 respectivel
27500 79 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74  y..** ^(Memory t
27510 6f 20 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72  o hold the error
27520 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
27530 69 73 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72  is managed inter
27540 6e 61 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70  nally..** The ap
27550 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e  plication does n
27560 6f 74 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79  ot need to worry
27570 20 61 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74   about freeing t
27580 68 65 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f  he result..** Ho
27590 77 65 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72  wever, the error
275a0 20 73 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65   string might be
275b0 20 6f 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20   overwritten or 
275c0 64 65 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a  deallocated by.*
275d0 2a 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  * subsequent cal
275e0 6c 73 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69  ls to other SQLi
275f0 74 65 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e  te interface fun
27600 63 74 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ctions.)^.**.** 
27610 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72  ^The sqlite3_err
27620 73 74 72 28 29 20 69 6e 74 65 72 66 61 63 65 20  str() interface 
27630 72 65 74 75 72 6e 73 20 74 68 65 20 45 6e 67 6c  returns the Engl
27640 69 73 68 2d 6c 61 6e 67 75 61 67 65 20 74 65 78  ish-language tex
27650 74 0a 2a 2a 20 74 68 61 74 20 64 65 73 63 72 69  t.** that descri
27660 62 65 73 20 74 68 65 20 5b 72 65 73 75 6c 74 20  bes the [result 
27670 63 6f 64 65 5d 2c 20 61 73 20 55 54 46 2d 38 2e  code], as UTF-8.
27680 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
27690 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
276a0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
276b0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
276c0 6c 6c 79 0a 2a 2a 20 61 6e 64 20 6d 75 73 74 20  lly.** and must 
276d0 6e 6f 74 20 62 65 20 66 72 65 65 64 20 62 79 20  not be freed by 
276e0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
276f0 5e 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  ^..**.** When th
27700 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
27710 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
27720 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
27730 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
27740 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
27750 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
27760 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
27770 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
27780 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
27790 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
277a0 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
277b0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
277c0 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
277d0 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
277e0 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
277f0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
27800 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
27810 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
27820 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
27830 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
27840 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
27850 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
27860 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
27870 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
27880 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
27890 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
278a0 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
278b0 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
278c0 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
278d0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
278e0 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
278f0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
27900 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
27910 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
27920 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
27930 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
27940 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
27950 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
27960 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
27970 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
27980 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
27990 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
279a0 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
279b0 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
279c0 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
279d0 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
279e0 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
279f0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
27a00 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
27a10 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 53 51  ot be set..*/.SQ
27a20 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
27a30 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
27a40 69 74 65 33 20 2a 64 62 29 3b 0a 53 51 4c 49 54  ite3 *db);.SQLIT
27a50 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
27a60 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
27a70 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
27a80 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
27a90 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
27aa0 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
27ab0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
27ac0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
27ad0 5f 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65  _errmsg16(sqlite
27ae0 33 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  3*);.SQLITE_API 
27af0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
27b00 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b  te3_errstr(int);
27b10 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27b20 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  : SQL Statement 
27b30 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52  Object.** KEYWOR
27b40 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74  DS: {prepared st
27b50 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72  atement} {prepar
27b60 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a  ed statements}.*
27b70 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65  *.** An instance
27b80 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20   of this object 
27b90 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e  represents a sin
27ba0 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  gle SQL statemen
27bb0 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63  t..** This objec
27bc0 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b  t is variously k
27bd0 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61  nown as a "prepa
27be0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  red statement" o
27bf0 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64  r a.** "compiled
27c00 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20   SQL statement" 
27c10 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22  or simply as a "
27c20 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a  statement"..**.*
27c30 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20  * The life of a 
27c40 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74  statement object
27c50 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20   goes something 
27c60 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a  like this:.**.**
27c70 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72   <ol>.** <li> Cr
27c80 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20  eate the object 
27c90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70  using [sqlite3_p
27ca0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
27cb0 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20  a related.**    
27cc0 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c    function..** <
27cd0 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20  li> Bind values 
27ce0 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74  to [host paramet
27cf0 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73  ers] using the s
27d00 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a  qlite3_bind_*().
27d10 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63  **      interfac
27d20 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20  es..** <li> Run 
27d30 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69  the SQL by calli
27d40 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
27d50 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  ()] one or more 
27d60 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52  times..** <li> R
27d70 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65  eset the stateme
27d80 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
27d90 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20  3_reset()] then 
27da0 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20  go back.**      
27db0 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74  to step 2.  Do t
27dc0 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65  his zero or more
27dd0 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
27de0 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65  Destroy the obje
27df0 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ct using [sqlite
27e00 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a  3_finalize()]..*
27e10 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65  * </ol>.**.** Re
27e20 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61  fer to documenta
27e30 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
27e40 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  al methods above
27e50 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
27e60 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
27e70 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
27e80 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73  t sqlite3_stmt s
27e90 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a  qlite3_stmt;../*
27ea0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
27eb0 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a  n-time Limits.**
27ec0 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72  .** ^(This inter
27ed0 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20  face allows the 
27ee0 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20  size of various 
27ef0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
27f00 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61   limited.** on a
27f10 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63   connection by c
27f20 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e  onnection basis.
27f30 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61    The first para
27f40 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
27f50 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
27f60 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69  tion] whose limi
27f70 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f  t is to be set o
27f80 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a  r queried.  The.
27f90 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  ** second parame
27fa0 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68  ter is one of th
27fb0 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  e [limit categor
27fc0 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65  ies] that define
27fd0 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63   a.** class of c
27fe0 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
27ff0 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54  size limited.  T
28000 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
28010 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77  er is the.** new
28020 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20   limit for that 
28030 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a  construct.)^.**.
28040 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c  ** ^If the new l
28050 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69  imit is a negati
28060 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c  ve number, the l
28070 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65  imit is unchange
28080 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68  d..** ^(For each
28090 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20   limit category 
280a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e  SQLITE_LIMIT_<i>
280b0 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69  NAME</i> there i
280c0 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  s a .** [limits 
280d0 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  | hard upper bou
280e0 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f  nd].** set at co
280f0 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20  mpile-time by a 
28100 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
28110 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b  acro called.** [
28120 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f  limits | SQLITE_
28130 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d  MAX_<i>NAME</i>]
28140 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49  ..** (The "_LIMI
28150 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  T_" in the name 
28160 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f  is changed to "_
28170 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74  MAX_".))^.** ^At
28180 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61  tempts to increa
28190 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65  se a limit above
281a0 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20   its hard upper 
281b0 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c  bound are.** sil
281c0 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20  ently truncated 
281d0 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65  to the hard uppe
281e0 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e  r bound..**.** ^
281f0 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  Regardless of wh
28200 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
28210 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67   limit was chang
28220 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c  ed, the .** [sql
28230 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e  ite3_limit()] in
28240 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
28250 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20  the prior value 
28260 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a  of the limit..**
28270 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64   ^Hence, to find
28280 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c   the current val
28290 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69  ue of a limit wi
282a0 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69  thout changing i
282b0 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76  t,.** simply inv
282c0 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61  oke this interfa
282d0 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72  ce with the thir
282e0 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20  d parameter set 
282f0 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e  to -1..**.** Run
28300 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65  -time limits are
28310 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
28320 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  e in application
28330 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a  s that manage.**
28340 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20   both their own 
28350 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
28360 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62  e and also datab
28370 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f  ases that are co
28380 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75  ntrolled.** by u
28390 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61  ntrusted externa
283a0 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65  l sources.  An e
283b0 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69  xample applicati
283c0 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a  on might be a.**
283d0 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61   web browser tha
283e0 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61  t has its own da
283f0 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72  tabases for stor
28400 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a  ing history and.
28410 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61  ** separate data
28420 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64  bases controlled
28430 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61   by JavaScript a
28440 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e  pplications down
28450 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68  loaded.** off th
28460 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65  e Internet.  The
28470 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
28480 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e  ses can be given
28490 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64   the.** large, d
284a0 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20  efault limits.  
284b0 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65  Databases manage
284c0 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f  d by external so
284d0 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20  urces can.** be 
284e0 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c  given much small
284f0 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e  er limits design
28500 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ed to prevent a 
28510 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63  denial of servic
28520 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65  e.** attack.  De
28530 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61  velopers might a
28540 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20  lso want to use 
28550 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  the [sqlite3_set
28560 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a  _authorizer()].*
28570 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66  * interface to f
28580 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75  urther control u
28590 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54  ntrusted SQL.  T
285a0 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64  he size of the d
285b0 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74  atabase.** creat
285c0 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74  ed by an untrust
285d0 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65  ed script can be
285e0 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67   contained using
285f0 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67   the.** [max_pag
28600 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41  e_count] [PRAGMA
28610 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e  ]..**.** New run
28620 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65  -time limit cate
28630 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64  gories may be ad
28640 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
28650 6c 65 61 73 65 73 2e 0a 2a 2f 0a 53 51 4c 49 54  leases..*/.SQLIT
28660 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
28670 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a  3_limit(sqlite3*
28680 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65  , int id, int ne
28690 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  wVal);../*.** CA
286a0 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65  PI3REF: Run-Time
286b0 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65   Limit Categorie
286c0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
286d0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20  limit category} 
286e0 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69  {*limit categori
286f0 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  es}.**.** These 
28700 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65  constants define
28710 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d   various perform
28720 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74  ance limits.** t
28730 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72  hat can be lower
28740 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75  ed at run-time u
28750 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69  sing [sqlite3_li
28760 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  mit()]..** The s
28770 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d  ynopsis of the m
28780 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76  eanings of the v
28790 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73  arious limits is
287a0 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a   shown below..**
287b0 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   Additional info
287c0 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c  rmation is avail
287d0 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20  able at [limits 
287e0 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69  | Limits in SQLi
287f0 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  te]..**.** <dl>.
28800 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28810 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74  T_LENGTH]] ^(<dt
28820 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45  >SQLITE_LIMIT_LE
28830 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  NGTH</dt>.** <dd
28840 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a  >The maximum siz
28850 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e 67 20  e of any string 
28860 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65  or BLOB or table
28870 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c   row, in bytes.<
28880 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
28890 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
288a0 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
288b0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
288c0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
288d0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
288e0 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c 20 73  ngth of an SQL s
288f0 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74  tatement, in byt
28900 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  es.</dd>)^.**.**
28910 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
28920 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53  COLUMN]] ^(<dt>S
28930 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
28940 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  MN</dt>.** <dd>T
28950 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
28960 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
28970 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69 74 69  a table definiti
28980 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20  on or in the.** 
28990 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20  result set of a 
289a0 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68 65 20  [SELECT] or the 
289b0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
289c0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20  f columns in an 
289d0 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61  index.** or in a
289e0 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20 47 52  n ORDER BY or GR
289f0 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f  OUP BY clause.</
28a00 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
28a10 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
28a20 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
28a30 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f  LITE_LIMIT_EXPR_
28a40 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  DEPTH</dt>.** <d
28a50 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65  d>The maximum de
28a60 70 74 68 20 6f 66 20 74 68 65 20 70 61 72 73 65  pth of the parse
28a70 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65 78 70   tree on any exp
28a80 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a  ression.</dd>)^.
28a90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
28aa0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
28ab0 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c  LECT]] ^(<dt>SQL
28ac0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
28ad0 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a  ND_SELECT</dt>.*
28ae0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
28af0 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65 72 6d  m number of term
28b00 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20  s in a compound 
28b10 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65 6e 74  SELECT statement
28b20 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
28b30 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44  [SQLITE_LIMIT_VD
28b40 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51  BE_OP]] ^(<dt>SQ
28b50 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
28b60 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  OP</dt>.** <dd>T
28b70 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
28b80 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69 6f 6e  r of instruction
28b90 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c 20 6d  s in a virtual m
28ba0 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a  achine program.*
28bb0 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d  * used to implem
28bc0 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61 74 65  ent an SQL state
28bd0 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69 6d 69  ment.  This limi
28be0 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  t is not current
28bf0 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20  ly.** enforced, 
28c00 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69 67 68  though that migh
28c10 74 20 62 65 20 61 64 64 65 64 20 69 6e 20 73 6f  t be added in so
28c20 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  me future releas
28c30 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c  e of.** SQLite.<
28c40 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
28c50 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
28c60 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74  TION_ARG]] ^(<dt
28c70 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  >SQLITE_LIMIT_FU
28c80 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a  NCTION_ARG</dt>.
28c90 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
28ca0 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  um number of arg
28cb0 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63  uments on a func
28cc0 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  tion.</dd>)^.**.
28cd0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
28ce0 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c  T_ATTACHED]] ^(<
28cf0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
28d00 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a  ATTACHED</dt>.**
28d10 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
28d20 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54 54 41   number of [ATTA
28d30 43 48 20 7c 20 61 74 74 61 63 68 65 64 20 64 61  CH | attached da
28d40 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e  tabases].)^</dd>
28d50 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
28d60 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
28d70 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e  RN_LENGTH]].** ^
28d80 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
28d90 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
28da0 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ENGTH</dt>.** <d
28db0 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  d>The maximum le
28dc0 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61 74 74  ngth of the patt
28dd0 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ern argument to 
28de0 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a  the [LIKE] or.**
28df0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
28e00 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  s.</dd>)^.**.** 
28e10 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  [[SQLITE_LIMIT_V
28e20 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d  ARIABLE_NUMBER]]
28e30 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
28e40 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f  _LIMIT_VARIABLE_
28e50 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  NUMBER</dt>.** <
28e60 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 69  dd>The maximum i
28e70 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66 20 61  ndex number of a
28e80 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 69  ny [parameter] i
28e90 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
28ea0 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  nt.)^.**.** [[SQ
28eb0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
28ec0 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74  ER_DEPTH]] ^(<dt
28ed0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52  >SQLITE_LIMIT_TR
28ee0 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e  IGGER_DEPTH</dt>
28ef0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
28f00 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72 65 63  mum depth of rec
28f10 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69 67 67  ursion for trigg
28f20 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c  ers.</dd>)^.** <
28f30 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  /dl>.*/.#define 
28f40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e  SQLITE_LIMIT_LEN
28f50 47 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  GTH             
28f60 20 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65         0.#define
28f70 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51   SQLITE_LIMIT_SQ
28f80 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20  L_LENGTH        
28f90 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
28fa0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  e SQLITE_LIMIT_C
28fb0 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20 20 20  OLUMN           
28fc0 20 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69           2.#defi
28fd0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
28fe0 45 58 50 52 5f 44 45 50 54 48 20 20 20 20 20 20  EXPR_DEPTH      
28ff0 20 20 20 20 20 20 20 20 20 20 33 0a 23 64 65 66            3.#def
29000 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
29010 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54  _COMPOUND_SELECT
29020 20 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65             4.#de
29030 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
29040 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20 20 20  T_VDBE_OP       
29050 20 20 20 20 20 20 20 20 20 20 20 20 35 0a 23 64              5.#d
29060 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
29070 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20  IT_FUNCTION_ARG 
29080 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a 23               6.#
29090 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
290a0 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20 20 20  MIT_ATTACHED    
290b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 37 0a                7.
290c0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
290d0 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52  IMIT_LIKE_PATTER
290e0 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 38  N_LENGTH       8
290f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29100 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e  LIMIT_VARIABLE_N
29110 55 4d 42 45 52 20 20 20 20 20 20 20 20 20 20 20  UMBER           
29120 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
29130 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
29140 45 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20  EPTH            
29150 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  10../*.** CAPI3R
29160 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e  EF: Compiling An
29170 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
29180 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c  * KEYWORDS: {SQL
29190 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69   statement compi
291a0 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78  ler}.**.** To ex
291b0 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71 75 65  ecute an SQL que
291c0 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69 72 73  ry, it must firs
291d0 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e  t be compiled in
291e0 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a  to a byte-code.*
291f0 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e 67 20  * program using 
29200 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72 6f 75  one of these rou
29210 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tines..**.** The
29220 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2c   first argument,
29230 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64 61 74   "db", is a [dat
29240 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
29250 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  ] obtained from 
29260 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63 63 65  a.** prior succe
29270 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73  ssful call to [s
29280 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
29290 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
292a0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
292b0 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54  e3_open16()].  T
292c0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
292d0 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20  ection must not 
292e0 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73 65 64  have been closed
292f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
29300 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53  nd argument, "zS
29310 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74 61 74  ql", is the stat
29320 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70  ement to be comp
29330 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a  iled, encoded.**
29340 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
29350 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54 68 65   or UTF-16.  The
29360 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
29370 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
29380 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69  repare_v2().** i
29390 6e 74 65 72 66 61 63 65 73 20 75 73 65 20 55 54  nterfaces use UT
293a0 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74 65 33  F-8, and sqlite3
293b0 5f 70 72 65 70 61 72 65 31 36 28 29 20 61 6e 64  _prepare16() and
293c0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
293d0 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65 20 55  16_v2().** use U
293e0 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  TF-16..**.** ^If
293f0 20 74 68 65 20 6e 42 79 74 65 20 61 72 67 75 6d   the nByte argum
29400 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68 61 6e  ent is less than
29410 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c   zero, then zSql
29420 20 69 73 20 72 65 61 64 20 75 70 20 74 6f 20 74   is read up to t
29430 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f  he.** first zero
29440 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66   terminator. ^If
29450 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65   nByte is non-ne
29460 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 20  gative, then it 
29470 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  is the maximum.*
29480 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62 79 74  * number of  byt
29490 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a 53 71  es read from zSq
294a0 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74 65 20  l.  ^When nByte 
294b0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
294c0 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72   the.** zSql str
294d0 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69 74 68  ing ends at eith
294e0 65 72 20 74 68 65 20 66 69 72 73 74 20 27 5c 30  er the first '\0
294f0 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30 27 20  00' or '\u0000' 
29500 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20  character or.** 
29510 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62 79 74  the nByte-th byt
29520 65 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  e, whichever com
29530 65 73 20 66 69 72 73 74 2e 20 49 66 20 74 68 65  es first. If the
29540 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a   caller knows.**
29550 20 74 68 61 74 20 74 68 65 20 73 75 70 70 6c 69   that the suppli
29560 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e 75 6c  ed string is nul
29570 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74 68 65  -terminated, the
29580 6e 20 74 68 65 72 65 20 69 73 20 61 20 73 6d 61  n there is a sma
29590 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63  ll.** performanc
295a0 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f 20 62  e advantage to b
295b0 65 20 67 61 69 6e 65 64 20 62 79 20 70 61 73 73  e gained by pass
295c0 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70 61 72  ing an nByte par
295d0 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a 20 69  ameter that.** i
295e0 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65 20 6e  s equal to the n
295f0 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
29600 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
29610 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c  ng <i>including<
29620 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74  /i>.** the nul-t
29630 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65 73 20  erminator bytes 
29640 61 73 20 74 68 69 73 20 73 61 76 65 73 20 53 51  as this saves SQ
29650 4c 69 74 65 20 66 72 6f 6d 20 68 61 76 69 6e 67  Lite from having
29660 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f   to.** make a co
29670 70 79 20 6f 66 20 74 68 65 20 69 6e 70 75 74 20  py of the input 
29680 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  string..**.** ^I
29690 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20  f pzTail is not 
296a0 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69  NULL then *pzTai
296b0 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70 6f 69  l is made to poi
296c0 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74 20  nt to the first 
296d0 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74 68 65  byte.** past the
296e0 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69 72 73   end of the firs
296f0 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  t SQL statement 
29700 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73 65 20  in zSql.  These 
29710 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a  routines only.**
29720 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66 69 72   compile the fir
29730 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  st statement in 
29740 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c  zSql, so *pzTail
29750 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
29760 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d  g to.** what rem
29770 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e  ains uncompiled.
29780 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20  .**.** ^*ppStmt 
29790 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67  is left pointing
297a0 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b   to a compiled [
297b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
297c0 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62 65 0a  nt] that can be.
297d0 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73 69 6e  ** executed usin
297e0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
297f0 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65 20 69  )].  ^If there i
29800 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53  s an error, *ppS
29810 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f  tmt is set.** to
29820 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20   NULL.  ^If the 
29830 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e 74 61  input text conta
29840 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66 20 74  ins no SQL (if t
29850 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e 20 65  he input is an e
29860 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f  mpty.** string o
29870 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65  r a comment) the
29880 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  n *ppStmt is set
29890 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65   to NULL..** The
298a0 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75   calling procedu
298b0 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c  re is responsibl
298c0 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67 20 74  e for deleting t
298d0 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53  he compiled.** S
298e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69  QL statement usi
298f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ng [sqlite3_fina
29900 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20 69 74  lize()] after it
29910 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
29920 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74  th it..** ppStmt
29930 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c   may not be NULL
29940 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63  ..**.** ^On succ
29950 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ess, the sqlite3
29960 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d 69 6c  _prepare() famil
29970 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20 72 65  y of routines re
29980 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
29990 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65 20 61  ;.** otherwise a
299a0 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  n [error code] i
299b0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  s returned..**.*
299c0 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72  * The sqlite3_pr
299d0 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64 20 73  epare_v2() and s
299e0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
299f0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 73  _v2() interfaces
29a00 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e   are.** recommen
29a10 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20  ded for all new 
29a20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20 74 77  programs. The tw
29a30 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66 61 63  o older interfac
29a40 65 73 20 61 72 65 20 72 65 74 61 69 6e 65 64 0a  es are retained.
29a50 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73  ** for backwards
29a60 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2c 20   compatibility, 
29a70 62 75 74 20 74 68 65 69 72 20 75 73 65 20 69 73  but their use is
29a80 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a   discouraged..**
29a90 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
29aa0 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 70 72  terfaces, the pr
29ab0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29ac0 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65 74 75  .** that is retu
29ad0 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c 69 74  rned (the [sqlit
29ae0 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29  e3_stmt] object)
29af0 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f 70 79   contains a copy
29b00 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69   of the.** origi
29b10 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20 54 68  nal SQL text. Th
29b20 69 73 20 63 61 75 73 65 73 20 74 68 65 20 5b 73  is causes the [s
29b30 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 69  qlite3_step()] i
29b40 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62  nterface to.** b
29b50 65 68 61 76 65 20 64 69 66 66 65 72 65 6e 74 6c  ehave differentl
29b60 79 20 69 6e 20 74 68 72 65 65 20 77 61 79 73 3a  y in three ways:
29b70 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
29b80 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64  li>.** ^If the d
29b90 61 74 61 62 61 73 65 20 73 63 68 65 6d 61 20 63  atabase schema c
29ba0 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61 64 20  hanges, instead 
29bb0 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  of returning [SQ
29bc0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61 73 20  LITE_SCHEMA] as 
29bd0 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75 73 65  it.** always use
29be0 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65  d to do, [sqlite
29bf0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 61  3_step()] will a
29c00 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
29c10 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a  ompile the SQL.*
29c20 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  * statement and 
29c30 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20 61 67  try to run it ag
29c40 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  ain..** </li>.**
29c50 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65  .** <li>.** ^Whe
29c60 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  n an error occur
29c70 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  s, [sqlite3_step
29c80 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
29c90 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74 61 69  one of the detai
29ca0 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f  led.** [error co
29cb0 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65  des] or [extende
29cc0 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20  d error codes]. 
29cd0 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62 65 68   ^The legacy beh
29ce0 61 76 69 6f 72 20 77 61 73 20 74 68 61 74 0a 2a  avior was that.*
29cf0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
29d00 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65  )] would only re
29d10 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63 20 5b  turn a generic [
29d20 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 72 65  SQLITE_ERROR] re
29d30 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64  sult code.** and
29d40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
29d50 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f 20 6d   would have to m
29d60 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63 61 6c  ake a second cal
29d70 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  l to [sqlite3_re
29d80 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64  set()].** in ord
29d90 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65 20 75  er to find the u
29da0 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73 65 20  nderlying cause 
29db0 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20  of the problem. 
29dc0 57 69 74 68 20 74 68 65 20 22 76 32 22 20 70 72  With the "v2" pr
29dd0 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61  epare.** interfa
29de0 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72 6c 79  ces, the underly
29df0 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72 20 74  ing reason for t
29e00 68 65 20 65 72 72 6f 72 20 69 73 20 72 65 74 75  he error is retu
29e10 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79  rned immediately
29e20 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
29e30 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
29e40 20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20   specific value 
29e50 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65  bound to [parame
29e60 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72 61 6d  ter | host param
29e70 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a  eter] in the .**
29e80 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 6d 69   WHERE clause mi
29e90 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
29ea0 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72  e choice of quer
29eb0 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73 74 61  y plan for a sta
29ec0 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20  tement,.** then 
29ed0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 69  the statement wi
29ee0 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61  ll be automatica
29ef0 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20  lly recompiled, 
29f00 61 73 20 69 66 20 74 68 65 72 65 20 68 61 64 20  as if there had 
29f10 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d  been .** a schem
29f20 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65  a change, on the
29f30 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74 65 33   first  [sqlite3
29f40 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f  _step()] call fo
29f50 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68 61 6e  llowing any chan
29f60 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  ge.** to the [sq
29f70 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 20  lite3_bind_text 
29f80 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74  | bindings] of t
29f90 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e  hat [parameter].
29fa0 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63 69 66   .** ^The specif
29fb0 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48 45 52  ic value of WHER
29fc0 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61 6d 65  E-clause [parame
29fd0 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75  ter] might influ
29fe0 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f  ence the .** cho
29ff0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
2a000 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  n if the paramet
2a010 65 72 20 69 73 20 74 68 65 20 6c 65 66 74 2d 68  er is the left-h
2a020 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20 5b 4c  and side of a [L
2a030 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42  IKE].** or [GLOB
2a040 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20 69 66  ] operator or if
2a050 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69   the parameter i
2a060 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e  s compared to an
2a070 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a   indexed column.
2a080 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51 4c 49  ** and the [SQLI
2a090 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d  TE_ENABLE_STAT3]
2a0a0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70   compile-time op
2a0b0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e  tion is enabled.
2a0c0 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69  .** the .** </li
2a0d0 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 53 51  >.** </ol>.*/.SQ
2a0e0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a0f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
2a100 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
2a110 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
2a120 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
2a130 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
2a140 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
2a150 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
2a160 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
2a170 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
2a180 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
2a190 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
2a1a0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
2a1b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
2a1c0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
2a1d0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
2a1e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
2a1f0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
2a200 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
2a210 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
2a220 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c 49   zSql */.);.SQLI
2a230 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74  TE_API int sqlit
2a240 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 0a 20  e3_prepare_v2(. 
2a250 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2a260 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2a270 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2a280 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
2a290 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2a2a0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
2a2b0 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
2a2c0 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
2a2d0 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
2a2e0 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
2a2f0 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
2a300 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
2a310 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
2a320 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
2a330 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
2a340 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
2a350 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
2a360 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
2a370 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51 4c  f zSql */.);.SQL
2a380 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69  ITE_API int sqli
2a390 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
2a3a0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
2a3b0 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
2a3c0 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
2a3d0 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
2a3e0 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
2a3f0 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
2a400 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
2a410 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
2a420 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
2a430 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
2a440 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
2a450 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
2a460 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
2a470 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
2a480 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
2a490 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
2a4a0 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
2a4b0 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
2a4c0 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 53 51  of zSql */.);.SQ
2a4d0 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
2a4e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
2a4f0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2a500 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
2a510 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
2a520 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
2a530 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
2a540 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
2a550 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
2a560 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
2a570 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
2a580 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
2a590 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
2a5a0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
2a5b0 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
2a5c0 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
2a5d0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
2a5e0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
2a5f0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
2a600 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
2a610 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
2a620 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a630 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
2a640 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
2a650 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
2a660 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
2a670 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
2a680 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
2a690 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
2a6a0 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
2a6b0 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
2a6c0 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
2a6d0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
2a6e0 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
2a6f0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2a700 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2a710 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2a720 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 53  re16_v2()]..*/.S
2a730 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2a740 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 71  char *sqlite3_sq
2a750 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  l(sqlite3_stmt *
2a760 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2a770 41 50 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69  API3REF: Determi
2a780 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61  ne If An SQL Sta
2a790 74 65 6d 65 6e 74 20 57 72 69 74 65 73 20 54 68  tement Writes Th
2a7a0 65 20 44 61 74 61 62 61 73 65 0a 2a 2a 0a 2a 2a  e Database.**.**
2a7b0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 74   ^The sqlite3_st
2a7c0 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 58 29 20 69  mt_readonly(X) i
2a7d0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
2a7e0 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f 29   true (non-zero)
2a7f0 20 69 66 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20   if.** and only 
2a800 69 66 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  if the [prepared
2a810 20 73 74 61 74 65 6d 65 6e 74 5d 20 58 20 6d 61   statement] X ma
2a820 6b 65 73 20 6e 6f 20 64 69 72 65 63 74 20 63 68  kes no direct ch
2a830 61 6e 67 65 73 20 74 6f 0a 2a 2a 20 74 68 65 20  anges to.** the 
2a840 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64  content of the d
2a850 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 2a 2a  atabase file..**
2a860 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 61  .** Note that [a
2a870 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2a880 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
2a890 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72 74 75 61 6c  ] or.** [virtual
2a8a0 20 74 61 62 6c 65 73 5d 20 6d 69 67 68 74 20 63   tables] might c
2a8b0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
2a8c0 73 65 20 69 6e 64 69 72 65 63 74 6c 79 20 61 73  se indirectly as
2a8d0 20 61 20 73 69 64 65 20 65 66 66 65 63 74 2e 20   a side effect. 
2a8e0 20 0a 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70   .** ^(For examp
2a8f0 6c 65 2c 20 69 66 20 61 6e 20 61 70 70 6c 69 63  le, if an applic
2a900 61 74 69 6f 6e 20 64 65 66 69 6e 65 73 20 61 20  ation defines a 
2a910 66 75 6e 63 74 69 6f 6e 20 22 65 76 61 6c 28 29  function "eval()
2a920 22 20 74 68 61 74 20 0a 2a 2a 20 63 61 6c 6c 73  " that .** calls
2a930 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
2a940 5d 2c 20 74 68 65 6e 20 74 68 65 20 66 6f 6c 6c  ], then the foll
2a950 6f 77 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  owing SQL statem
2a960 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a 20 63 68 61  ent would.** cha
2a970 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73 65  nge the database
2a980 20 66 69 6c 65 20 74 68 72 6f 75 67 68 20 73 69   file through si
2a990 64 65 2d 65 66 66 65 63 74 73 3a 0a 2a 2a 0a 2a  de-effects:.**.*
2a9a0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
2a9b0 72 65 3e 0a 2a 2a 20 20 20 20 53 45 4c 45 43 54  re>.**    SELECT
2a9c0 20 65 76 61 6c 28 27 44 45 4c 45 54 45 20 46 52   eval('DELETE FR
2a9d0 4f 4d 20 74 31 27 29 20 46 52 4f 4d 20 74 32 3b  OM t1') FROM t2;
2a9e0 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
2a9f0 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 75  kquote>.**.** Bu
2aa00 74 20 62 65 63 61 75 73 65 20 74 68 65 20 5b 53  t because the [S
2aa10 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2aa20 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65   does not change
2aa30 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
2aa40 6c 65 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2c 20  le.** directly, 
2aa50 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2aa60 64 6f 6e 6c 79 28 29 20 77 6f 75 6c 64 20 73 74  donly() would st
2aa70 69 6c 6c 20 72 65 74 75 72 6e 20 74 72 75 65 2e  ill return true.
2aa80 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72 61 6e 73 61  )^.**.** ^Transa
2aa90 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 20 73 74  ction control st
2aaa0 61 74 65 6d 65 6e 74 73 20 73 75 63 68 20 61 73  atements such as
2aab0 20 5b 42 45 47 49 4e 5d 2c 20 5b 43 4f 4d 4d 49   [BEGIN], [COMMI
2aac0 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2c 0a  T], [ROLLBACK],.
2aad0 2a 2a 20 5b 53 41 56 45 50 4f 49 4e 54 5d 2c 20  ** [SAVEPOINT], 
2aae0 61 6e 64 20 5b 52 45 4c 45 41 53 45 5d 20 63 61  and [RELEASE] ca
2aaf0 75 73 65 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  use sqlite3_stmt
2ab00 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
2ab10 65 74 75 72 6e 20 74 72 75 65 2c 0a 2a 2a 20 73  eturn true,.** s
2ab20 69 6e 63 65 20 74 68 65 20 73 74 61 74 65 6d 65  ince the stateme
2ab30 6e 74 73 20 74 68 65 6d 73 65 6c 76 65 73 20 64  nts themselves d
2ab40 6f 20 6e 6f 74 20 61 63 74 75 61 6c 6c 79 20 6d  o not actually m
2ab50 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62 61  odify the databa
2ab60 73 65 20 62 75 74 0a 2a 2a 20 72 61 74 68 65 72  se but.** rather
2ab70 20 74 68 65 79 20 63 6f 6e 74 72 6f 6c 20 74 68   they control th
2ab80 65 20 74 69 6d 69 6e 67 20 6f 66 20 77 68 65 6e  e timing of when
2ab90 20 6f 74 68 65 72 20 73 74 61 74 65 6d 65 6e 74   other statement
2aba0 73 20 6d 6f 64 69 66 79 20 74 68 65 20 0a 2a 2a  s modify the .**
2abb0 20 64 61 74 61 62 61 73 65 2e 20 20 5e 54 68 65   database.  ^The
2abc0 20 5b 41 54 54 41 43 48 5d 20 61 6e 64 20 5b 44   [ATTACH] and [D
2abd0 45 54 41 43 48 5d 20 73 74 61 74 65 6d 65 6e 74  ETACH] statement
2abe0 73 20 61 6c 73 6f 20 63 61 75 73 65 0a 2a 2a 20  s also cause.** 
2abf0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
2ac00 64 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72  donly() to retur
2ac10 6e 20 74 72 75 65 20 73 69 6e 63 65 2c 20 77 68  n true since, wh
2ac20 69 6c 65 20 74 68 6f 73 65 20 73 74 61 74 65 6d  ile those statem
2ac30 65 6e 74 73 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ents.** change t
2ac40 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
2ac50 20 6f 66 20 61 20 64 61 74 61 62 61 73 65 20 63   of a database c
2ac60 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74 68 65 79 20  onnection, they 
2ac70 64 6f 20 6e 6f 74 20 6d 61 6b 65 20 0a 2a 2a 20  do not make .** 
2ac80 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20 63  changes to the c
2ac90 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 64 61  ontent of the da
2aca0 74 61 62 61 73 65 20 66 69 6c 65 73 20 6f 6e 20  tabase files on 
2acb0 64 69 73 6b 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  disk..*/.SQLITE_
2acc0 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
2acd0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
2ace0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2acf0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2ad00 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
2ad10 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  f A Prepared Sta
2ad20 74 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20  tement Has Been 
2ad30 52 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  Reset.**.** ^The
2ad40 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75   sqlite3_stmt_bu
2ad50 73 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20  sy(S) interface 
2ad60 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
2ad70 6e 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a  n-zero) if the.*
2ad80 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
2ad90 65 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65  ement] S has bee
2ada0 6e 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61  n stepped at lea
2adb0 73 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a  st once using .*
2adc0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
2add0 53 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20  S)] but has not 
2ade0 72 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  run to completio
2adf0 6e 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74  n and/or has not
2ae00 20 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20   .** been reset 
2ae10 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
2ae20 65 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20  eset(S)].  ^The 
2ae30 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
2ae40 79 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  y(S).** interfac
2ae50 65 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20  e returns false 
2ae60 69 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70  if S is a NULL p
2ae70 6f 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73  ointer.  If S is
2ae80 20 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20   not a .** NULL 
2ae90 70 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e  pointer and is n
2aea0 6f 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ot a pointer to 
2aeb0 61 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65  a valid [prepare
2aec0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2aed0 6f 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65  object, then the
2aee0 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64   behavior is und
2aef0 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2af00 62 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e  bly undesirable.
2af10 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65  .**.** This inte
2af20 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65  rface can be use
2af30 64 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  d in combination
2af40 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73   [sqlite3_next_s
2af50 74 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63  tmt()].** to loc
2af60 61 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64  ate all prepared
2af70 20 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f   statements asso
2af80 63 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61  ciated with a da
2af90 74 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65  tabase .** conne
2afa0 63 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69  ction that are i
2afb0 6e 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20  n need of being 
2afc0 72 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e  reset.  This can
2afd0 20 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72   be used,.** for
2afe0 20 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61   example, in dia
2aff0 67 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73  gnostic routines
2b000 20 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70   to search for p
2b010 72 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74  repared .** stat
2b020 65 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20  ements that are 
2b030 68 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61  holding a transa
2b040 63 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 53  ction open..*/.S
2b050 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2b060 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
2b070 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
2b080 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2b090 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
2b0a0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
2b0b0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
2b0c0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2b0d0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
2b0e0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
2b0f0 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
2b100 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
2b110 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
2b120 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
2b130 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
2b140 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
2b150 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
2b160 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
2b170 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
2b180 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
2b190 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
2b1a0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
2b1b0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
2b1c0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
2b1d0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
2b1e0 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
2b1f0 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
2b200 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
2b210 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2b220 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
2b230 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
2b240 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
2b250 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
2b260 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
2b270 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b280 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
2b290 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
2b2a0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
2b2b0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
2b2c0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2b2d0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
2b2e0 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
2b2f0 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
2b300 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
2b310 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
2b320 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
2b330 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
2b340 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
2b350 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
2b360 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
2b370 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
2b380 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
2b390 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
2b3a0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
2b3b0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
2b3c0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
2b3d0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
2b3e0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2b3f0 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
2b400 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
2b410 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
2b420 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
2b430 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
2b440 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
2b450 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
2b460 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
2b470 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
2b480 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
2b490 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
2b4a0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
2b4b0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
2b4c0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
2b4d0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
2b4e0 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
2b4f0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2b500 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
2b510 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
2b520 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
2b530 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
2b540 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
2b550 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
2b560 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
2b570 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
2b580 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
2b590 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
2b5a0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
2b5b0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
2b5c0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
2b5d0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
2b5e0 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
2b5f0 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
2b600 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
2b610 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
2b620 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
2b630 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
2b640 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
2b650 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
2b660 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
2b670 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
2b680 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
2b690 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
2b6a0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
2b6b0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
2b6c0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
2b6d0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
2b6e0 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
2b6f0 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
2b700 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
2b710 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
2b720 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
2b730 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
2b740 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
2b750 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
2b760 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
2b770 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
2b780 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
2b790 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2b7a0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2b7b0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
2b7c0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
2b7d0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
2b7e0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
2b7f0 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
2b800 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
2b810 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
2b820 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2b830 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
2b840 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
2b850 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
2b860 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
2b870 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2b880 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
2b890 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
2b8a0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
2b8b0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
2b8c0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
2b8d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2b8e0 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
2b8f0 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
2b900 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
2b910 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
2b920 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
2b930 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
2b940 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
2b950 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
2b960 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b970 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
2b980 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
2b990 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
2b9a0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
2b9b0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
2b9c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
2b9d0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
2b9e0 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
2b9f0 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2ba00 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
2ba10 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
2ba20 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2ba30 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
2ba40 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
2ba50 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
2ba60 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
2ba70 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
2ba80 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
2ba90 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
2baa0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
2bab0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2bac0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
2bad0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
2bae0 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
2baf0 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
2bb00 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
2bb10 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
2bb20 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
2bb30 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
2bb40 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
2bb50 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
2bb60 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
2bb70 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
2bb80 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
2bb90 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
2bba0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2bbb0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
2bbc0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
2bbd0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
2bbe0 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
2bbf0 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
2bc00 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
2bc10 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
2bc20 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
2bc30 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
2bc40 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
2bc50 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
2bc60 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
2bc70 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
2bc80 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
2bc90 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
2bca0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
2bcb0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
2bcc0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
2bcd0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
2bce0 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
2bcf0 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
2bd00 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
2bd10 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
2bd20 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
2bd30 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
2bd40 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
2bd50 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
2bd60 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2bd70 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
2bd80 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
2bd90 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2bda0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
2bdb0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
2bdc0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
2bdd0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
2bde0 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
2bdf0 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
2be00 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
2be10 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
2be20 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
2be30 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
2be40 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
2be50 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
2be60 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
2be70 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
2be80 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
2be90 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
2bea0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
2beb0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
2bec0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
2bed0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
2bee0 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
2bef0 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
2bf00 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
2bf10 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
2bf20 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
2bf30 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
2bf40 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
2bf50 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
2bf60 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
2bf70 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
2bf80 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2bf90 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
2bfa0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
2bfb0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
2bfc0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
2bfd0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
2bfe0 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
2bff0 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
2c000 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
2c010 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
2c020 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
2c030 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
2c040 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
2c050 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
2c060 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
2c070 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
2c080 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
2c090 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
2c0a0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
2c0b0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
2c0c0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
2c0d0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
2c0e0 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
2c0f0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2c100 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
2c110 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
2c120 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
2c130 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
2c140 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
2c150 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
2c160 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
2c170 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
2c180 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
2c190 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2c1a0 62 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73  bind_text() or s
2c1b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2c1c0 31 36 28 29 0a 2a 2a 20 69 73 20 6e 65 67 61 74  16().** is negat
2c1d0 69 76 65 2c 20 74 68 65 6e 20 74 68 65 20 6c 65  ive, then the le
2c1e0 6e 67 74 68 20 6f 66 20 74 68 65 20 73 74 72 69  ngth of the stri
2c1f0 6e 67 20 69 73 0a 2a 2a 20 74 68 65 20 6e 75 6d  ng is.** the num
2c200 62 65 72 20 6f 66 20 62 79 74 65 73 20 75 70 20  ber of bytes up 
2c210 74 6f 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  to the first zer
2c220 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a  o terminator..**
2c230 20 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   If the fourth p
2c240 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2c250 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20  te3_bind_blob() 
2c260 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2c270 6e 0a 2a 2a 20 74 68 65 20 62 65 68 61 76 69 6f  n.** the behavio
2c280 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a  r is undefined..
2c290 2a 2a 20 49 66 20 61 20 6e 6f 6e 2d 6e 65 67 61  ** If a non-nega
2c2a0 74 69 76 65 20 66 6f 75 72 74 68 20 70 61 72 61  tive fourth para
2c2b0 6d 65 74 65 72 20 69 73 20 70 72 6f 76 69 64 65  meter is provide
2c2c0 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  d to sqlite3_bin
2c2d0 64 5f 74 65 78 74 28 29 0a 2a 2a 20 6f 72 20 73  d_text().** or s
2c2e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
2c2f0 31 36 28 29 20 74 68 65 6e 20 74 68 61 74 20 70  16() then that p
2c300 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2c310 20 74 68 65 20 62 79 74 65 20 6f 66 66 73 65 74   the byte offset
2c320 0a 2a 2a 20 77 68 65 72 65 20 74 68 65 20 4e 55  .** where the NU
2c330 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f 75  L terminator wou
2c340 6c 64 20 6f 63 63 75 72 20 61 73 73 75 6d 69 6e  ld occur assumin
2c350 67 20 74 68 65 20 73 74 72 69 6e 67 20 77 65 72  g the string wer
2c360 65 20 4e 55 4c 0a 2a 2a 20 74 65 72 6d 69 6e 61  e NUL.** termina
2c370 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c  ted.  If any NUL
2c380 20 63 68 61 72 61 63 74 65 72 73 20 6f 63 63 75   characters occu
2c390 72 20 61 74 20 62 79 74 65 20 6f 66 66 73 65 74  r at byte offset
2c3a0 73 20 6c 65 73 73 20 74 68 61 6e 20 0a 2a 2a 20  s less than .** 
2c3b0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2c3c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
2c3d0 72 20 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c  r then the resul
2c3e0 74 69 6e 67 20 73 74 72 69 6e 67 20 76 61 6c 75  ting string valu
2c3f0 65 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 74 61 69  e will.** contai
2c400 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 2e  n embedded NULs.
2c410 20 20 54 68 65 20 72 65 73 75 6c 74 20 6f 66 20    The result of 
2c420 65 78 70 72 65 73 73 69 6f 6e 73 20 69 6e 76 6f  expressions invo
2c430 6c 76 69 6e 67 20 73 74 72 69 6e 67 73 0a 2a 2a  lving strings.**
2c440 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
2c450 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
2c460 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
2c470 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  th argument to s
2c480 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2c490 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  (), sqlite3_bind
2c4a0 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a 20  _text(), and.** 
2c4b0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2c4c0 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74 72  t16() is a destr
2c4d0 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64 69  uctor used to di
2c4e0 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f  spose of the BLO
2c4f0 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20 61  B or.** string a
2c500 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73 20  fter SQLite has 
2c510 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
2c520 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63 74  .  ^The destruct
2c530 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a 20  or is called.** 
2c540 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
2c550 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  e BLOB or string
2c560 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61 6c   even if the cal
2c570 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  l to sqlite3_bin
2c580 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71 6c  d_blob(),.** sql
2c590 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
2c5a0 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  , or sqlite3_bin
2c5b0 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c 73  d_text16() fails
2c5c0 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  .  .** ^If the f
2c5d0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69 73  ifth argument is
2c5e0 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c 20  .** the special 
2c5f0 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53 54  value [SQLITE_ST
2c600 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c 69  ATIC], then SQLi
2c610 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  te assumes that 
2c620 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  the.** informati
2c630 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63 2c  on is in static,
2c640 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63 65   unmanaged space
2c650 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e 65   and does not ne
2c660 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e 0a  ed to be freed..
2c670 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74 68  ** ^If the fifth
2c680 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74 68   argument has th
2c690 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f  e value [SQLITE_
2c6a0 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65 6e  TRANSIENT], then
2c6b0 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65 73  .** SQLite makes
2c6c0 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65   its own private
2c6d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61 74   copy of the dat
2c6e0 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20 62  a immediately, b
2c6f0 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71 6c  efore.** the sql
2c700 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
2c710 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a 2a  utine returns..*
2c720 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2c730 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
2c740 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73 20  ) routine binds 
2c750 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74 68  a BLOB of length
2c760 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66 69   N that.** is fi
2c770 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65 73  lled with zeroes
2c780 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20 75  .  ^A zeroblob u
2c790 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f 75  ses a fixed amou
2c7a0 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a 20  nt of memory.** 
2c7b0 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65 72  (just an integer
2c7c0 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69 7a   to hold its siz
2c7d0 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20 62  e) while it is b
2c7e0 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e 0a  eing processed..
2c7f0 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72 65  ** Zeroblobs are
2c800 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65 72   intended to ser
2c810 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64 65  ve as placeholde
2c820 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68 6f  rs for BLOBs who
2c830 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69 73  se.** content is
2c840 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20 75   later written u
2c850 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
2c860 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e 63  _blob_open | inc
2c870 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49 2f  remental BLOB I/
2c880 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 20  O] routines..** 
2c890 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c 75  ^A negative valu
2c8a0 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62 6c  e for the zerobl
2c8b0 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61 20  ob results in a 
2c8c0 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42  zero-length BLOB
2c8d0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79 20  ..**.** ^If any 
2c8e0 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  of the sqlite3_b
2c8f0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
2c900 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74 68   are called with
2c910 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a   a NULL pointer.
2c920 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65 70  ** for the [prep
2c930 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2c940 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61 72  or with a prepar
2c950 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f 72  ed statement for
2c960 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69 74   which.** [sqlit
2c970 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 62  e3_step()] has b
2c980 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65 20  een called more 
2c990 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b 73  recently than [s
2c9a0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c  qlite3_reset()],
2c9b0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61 6c  .** then the cal
2c9c0 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  l will return [S
2c9d0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20  QLITE_MISUSE].  
2c9e0 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f 62  If any sqlite3_b
2c9f0 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69 6e  ind_().** routin
2ca00 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b 70  e is passed a [p
2ca10 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2ca20 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65 6e  t] that has been
2ca30 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65 0a   finalized, the.
2ca40 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64  ** result is und
2ca50 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61  efined and proba
2ca60 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a 0a  bly harmful..**.
2ca70 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72 65  ** ^Bindings are
2ca80 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79 20   not cleared by 
2ca90 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  the [sqlite3_res
2caa0 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a 2a  et()] routine..*
2cab0 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61 6d  * ^Unbound param
2cac0 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72 70  eters are interp
2cad0 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a 2a  reted as NULL..*
2cae0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2caf0 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e 65  3_bind_* routine
2cb00 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
2cb10 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20  _OK] on success 
2cb20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72 20  or an.** [error 
2cb30 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69 6e  code] if anythin
2cb40 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
2cb50 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45 5d   ^[SQLITE_RANGE]
2cb60 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
2cb70 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  the parameter.**
2cb80 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66   index is out of
2cb90 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49 54   range.  ^[SQLIT
2cba0 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74 75  E_NOMEM] is retu
2cbb0 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28 29  rned if malloc()
2cbc0 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53 65   fails..**.** Se
2cbd0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
2cbe0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
2cbf0 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  count()],.** [sq
2cc00 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2cc10 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e  eter_name()], an
2cc20 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  d [sqlite3_bind_
2cc30 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
2cc40 29 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  )]..*/.SQLITE_AP
2cc50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2cc60 6e 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  nd_blob(sqlite3_
2cc70 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2cc80 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20  t void*, int n, 
2cc90 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2cca0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ccb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
2ccc0 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
2ccd0 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
2cce0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ccf0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
2cd00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2cd10 69 6e 74 2c 20 69 6e 74 29 3b 0a 53 51 4c 49 54  int, int);.SQLIT
2cd20 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2cd30 33 5f 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c  3_bind_int64(sql
2cd40 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2cd50 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b   sqlite3_int64);
2cd60 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2cd70 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
2cd80 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
2cd90 20 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50   int);.SQLITE_AP
2cda0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  I int sqlite3_bi
2cdb0 6e 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  nd_text(sqlite3_
2cdc0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
2cdd0 74 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20  t char*, int n, 
2cde0 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
2cdf0 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20  .SQLITE_API int 
2ce00 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
2ce10 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2ce20 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
2ce30 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2ce40 29 28 76 6f 69 64 2a 29 29 3b 0a 53 51 4c 49 54  )(void*));.SQLIT
2ce50 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
2ce60 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
2ce70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2ce80 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
2ce90 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
2cea0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  PI int sqlite3_b
2ceb0 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c  ind_zeroblob(sql
2cec0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
2ced0 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int n);../*.** 
2cee0 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72  CAPI3REF: Number
2cef0 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65   Of SQL Paramete
2cf00 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  rs.**.** ^This r
2cf10 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73  outine can be us
2cf20 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e  ed to find the n
2cf30 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61  umber of [SQL pa
2cf40 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20  rameters].** in 
2cf50 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2cf60 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72  ement].  SQL par
2cf70 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65  ameters are toke
2cf80 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72  ns of the.** for
2cf90 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22  m "?", "?NNN", "
2cfa0 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f  :AAA", "$AAA", o
2cfb0 72 20 22 40 41 41 41 22 20 74 68 61 74 20 73 65  r "@AAA" that se
2cfc0 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68  rve as.** placeh
2cfd0 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65  olders for value
2cfe0 73 20 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69  s that are [sqli
2cff0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20  te3_bind_blob | 
2d000 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65  bound].** to the
2d010 20 70 61 72 61 6d 65 74 65 72 73 20 61 74 20 61   parameters at a
2d020 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a   later time..**.
2d030 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e  ** ^(This routin
2d040 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72  e actually retur
2d050 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  ns the index of 
2d060 74 68 65 20 6c 61 72 67 65 73 74 20 28 72 69 67  the largest (rig
2d070 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d  htmost).** param
2d080 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f  eter. For all fo
2d090 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c  rms except ?NNN,
2d0a0 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65   this will corre
2d0b0 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20  spond to the.** 
2d0c0 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65  number of unique
2d0d0 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66   parameters.  If
2d0e0 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74   parameters of t
2d0f0 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65  he ?NNN form are
2d100 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20   used,.** there 
2d110 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e 20 74  may be gaps in t
2d120 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a  he list.)^.**.**
2d130 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2d140 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2d150 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2d160 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2d170 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
2d180 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2d190 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2d1a0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 53  r_index()]..*/.S
2d1b0 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71  QLITE_API int sq
2d1c0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2d1d0 65 74 65 72 5f 63 6f 75 6e 74 28 73 71 6c 69 74  eter_count(sqlit
2d1e0 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a  e3_stmt*);../*.*
2d1f0 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65  * CAPI3REF: Name
2d200 20 4f 66 20 41 20 48 6f 73 74 20 50 61 72 61 6d   Of A Host Param
2d210 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eter.**.** ^The 
2d220 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
2d230 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50 2c 4e 29  ameter_name(P,N)
2d240 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2d250 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f  ns.** the name o
2d260 66 20 74 68 65 20 4e 2d 74 68 20 5b 53 51 4c 20  f the N-th [SQL 
2d270 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68  parameter] in th
2d280 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2d290 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53  ement] P..** ^(S
2d2a0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  QL parameters of
2d2b0 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22   the form "?NNN"
2d2c0 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
2d2d0 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
2d2e0 2a 20 68 61 76 65 20 61 20 6e 61 6d 65 20 77 68  * have a name wh
2d2f0 69 63 68 20 69 73 20 74 68 65 20 73 74 72 69 6e  ich is the strin
2d300 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  g "?NNN" or ":AA
2d310 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
2d320 22 24 41 41 41 22 0a 2a 2a 20 72 65 73 70 65 63  "$AAA".** respec
2d330 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74  tively..** In ot
2d340 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 69  her words, the i
2d350 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72 20 22 24  nitial ":" or "$
2d360 22 20 6f 72 20 22 40 22 20 6f 72 20 22 3f 22 0a  " or "@" or "?".
2d370 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65 64 20 61  ** is included a
2d380 73 20 70 61 72 74 20 6f 66 20 74 68 65 20 6e 61  s part of the na
2d390 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65  me.)^.** ^Parame
2d3a0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
2d3b0 20 22 3f 22 20 77 69 74 68 6f 75 74 20 61 20 66   "?" without a f
2d3c0 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65 67 65 72  ollowing integer
2d3d0 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a   have no name.**
2d3e0 20 61 6e 64 20 61 72 65 20 72 65 66 65 72 72 65   and are referre
2d3f0 64 20 74 6f 20 61 73 20 22 6e 61 6d 65 6c 65 73  d to as "nameles
2d400 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d 6f 75 73  s" or "anonymous
2d410 20 70 61 72 61 6d 65 74 65 72 73 22 2e 0a 2a 2a   parameters"..**
2d420 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 68  .** ^The first h
2d430 6f 73 74 20 70 61 72 61 6d 65 74 65 72 20 68 61  ost parameter ha
2d440 73 20 61 6e 20 69 6e 64 65 78 20 6f 66 20 31 2c  s an index of 1,
2d450 20 6e 6f 74 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49   not 0..**.** ^I
2d460 66 20 74 68 65 20 76 61 6c 75 65 20 4e 20 69 73  f the value N is
2d470 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20 6f 72   out of range or
2d480 20 69 66 20 74 68 65 20 4e 2d 74 68 20 70 61 72   if the N-th par
2d490 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 6e 61 6d  ameter is.** nam
2d4a0 65 6c 65 73 73 2c 20 74 68 65 6e 20 4e 55 4c 4c  eless, then NULL
2d4b0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 5e   is returned.  ^
2d4c0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2d4d0 69 6e 67 20 69 73 0a 2a 2a 20 61 6c 77 61 79 73  ing is.** always
2d4e0 20 69 6e 20 55 54 46 2d 38 20 65 6e 63 6f 64 69   in UTF-8 encodi
2d4f0 6e 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 6e  ng even if the n
2d500 61 6d 65 64 20 70 61 72 61 6d 65 74 65 72 20 77  amed parameter w
2d510 61 73 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 6c 79  as.** originally
2d520 20 73 70 65 63 69 66 69 65 64 20 61 73 20 55 54   specified as UT
2d530 46 2d 31 36 20 69 6e 20 5b 73 71 6c 69 74 65 33  F-16 in [sqlite3
2d540 5f 70 72 65 70 61 72 65 31 36 28 29 5d 20 6f 72  _prepare16()] or
2d550 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2d560 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2d570 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2d580 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2d590 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2d5a0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2d5b0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2d5c0 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2d5d0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2d5e0 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2d5f0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2d600 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2d610 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2d620 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2d630 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  mt*, int);../*.*
2d640 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65  * CAPI3REF: Inde
2d650 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72  x Of A Parameter
2d660 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61   With A Given Na
2d670 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e  me.**.** ^Return
2d680 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e   the index of an
2d690 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67   SQL parameter g
2d6a0 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20  iven its name.  
2d6b0 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61  ^The.** index va
2d6c0 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20  lue returned is 
2d6d0 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65  suitable for use
2d6e0 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a   as the second.*
2d6f0 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b  * parameter to [
2d700 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2d710 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
2d720 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69  ].  ^A zero.** i
2d730 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f  s returned if no
2d740 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65   matching parame
2d750 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e  ter is found.  ^
2d760 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  The parameter.**
2d770 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69   name must be gi
2d780 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65  ven in UTF-8 eve
2d790 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61  n if the origina
2d7a0 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77  l statement.** w
2d7b0 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d  as prepared from
2d7c0 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69   UTF-16 text usi
2d7d0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
2d7e0 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a  are16_v2()]..**.
2d7f0 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
2d800 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2d810 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
2d820 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
2d830 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
2d840 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  t()], and.** [sq
2d850 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
2d860 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
2d870 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74  /.SQLITE_API int
2d880 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
2d890 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73 71  rameter_index(sq
2d8a0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f 6e  lite3_stmt*, con
2d8b0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
2d8c0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2d8d0 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e 64  : Reset All Bind
2d8e0 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61 72  ings On A Prepar
2d8f0 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 0a  ed Statement.**.
2d900 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f 20  ** ^Contrary to 
2d910 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f 66  the intuition of
2d920 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33 5f   many, [sqlite3_
2d930 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e 6f  reset()] does no
2d940 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20 5b  t reset.** the [
2d950 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
2d960 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  b | bindings] on
2d970 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2d980 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73 65  tement]..** ^Use
2d990 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74 6f   this routine to
2d9a0 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74 20   reset all host 
2d9b0 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e 55  parameters to NU
2d9c0 4c 4c 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  LL..*/.SQLITE_AP
2d9d0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c  I int sqlite3_cl
2d9e0 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c  ear_bindings(sql
2d9f0 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
2da00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
2da10 6d 62 65 72 20 4f 66 20 43 6f 6c 75 6d 6e 73 20  mber Of Columns 
2da20 49 6e 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a  In A Result Set.
2da30 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
2da40 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
2da50 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
2da60 74 20 73 65 74 20 72 65 74 75 72 6e 65 64 20 62  t set returned b
2da70 79 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  y the.** [prepar
2da80 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 5e  ed statement]. ^
2da90 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
2daa0 75 72 6e 73 20 30 20 69 66 20 70 53 74 6d 74 20  urns 0 if pStmt 
2dab0 69 73 20 61 6e 20 53 51 4c 0a 2a 2a 20 73 74 61  is an SQL.** sta
2dac0 74 65 6d 65 6e 74 20 74 68 61 74 20 64 6f 65 73  tement that does
2dad0 20 6e 6f 74 20 72 65 74 75 72 6e 20 64 61 74 61   not return data
2dae0 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 61 6e   (for example an
2daf0 20 5b 55 50 44 41 54 45 5d 29 2e 0a 2a 2a 0a 2a   [UPDATE])..**.*
2db00 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
2db10 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
2db20 29 5d 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  )].*/.SQLITE_API
2db30 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c   int sqlite3_col
2db40 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2db50 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2db60 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2db70 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2db80 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2db90 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2dba0 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2dbb0 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2dbc0 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2dbd0 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2dbe0 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2dbf0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2dc00 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2dc10 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2dc20 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2dc30 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2dc40 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2dc50 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2dc60 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2dc70 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2dc80 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2dc90 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2dca0 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2dcb0 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2dcc0 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2dcd0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2dce0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2dcf0 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2dd00 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2dd10 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2dd20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2dd30 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2dd40 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2dd50 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2dd60 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2dd70 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2dd80 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2dd90 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2dda0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ddb0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2ddc0 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2ddd0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2dde0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2ddf0 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2de00 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2de10 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2de20 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2de30 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2de40 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2de50 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2de60 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2de70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2de80 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2de90 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2dea0 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2deb0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2dec0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2ded0 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2dee0 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2def0 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2df00 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2df10 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2df20 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2df30 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2df40 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2df50 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2df60 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2df70 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2df80 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2df90 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2dfa0 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2dfb0 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2dfc0 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2dfd0 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2dfe0 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2dff0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2e000 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2e010 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2e020 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2e030 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2e040 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2e050 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2e060 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2e070 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
2e080 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2e090 20 4e 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20   N);.SQLITE_API 
2e0a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2e0b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31  te3_column_name1
2e0c0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2e0d0 20 69 6e 74 20 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20   int N);../*.** 
2e0e0 43 41 50 49 33 52 45 46 3a 20 53 6f 75 72 63 65  CAPI3REF: Source
2e0f0 20 4f 66 20 44 61 74 61 20 49 6e 20 41 20 51 75   Of Data In A Qu
2e100 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a  ery Result.**.**
2e110 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2e120 20 70 72 6f 76 69 64 65 20 61 20 6d 65 61 6e 73   provide a means
2e130 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 74 68   to determine th
2e140 65 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  e database, tabl
2e150 65 2c 20 61 6e 64 0a 2a 2a 20 74 61 62 6c 65 20  e, and.** table 
2e160 63 6f 6c 75 6d 6e 20 74 68 61 74 20 69 73 20 74  column that is t
2e170 68 65 20 6f 72 69 67 69 6e 20 6f 66 20 61 20 70  he origin of a p
2e180 61 72 74 69 63 75 6c 61 72 20 72 65 73 75 6c 74  articular result
2e190 20 63 6f 6c 75 6d 6e 20 69 6e 0a 2a 2a 20 5b 53   column in.** [S
2e1a0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2e1b0 2e 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  ..** ^The name o
2e1c0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  f the database o
2e1d0 72 20 74 61 62 6c 65 20 6f 72 20 63 6f 6c 75 6d  r table or colum
2e1e0 6e 20 63 61 6e 20 62 65 20 72 65 74 75 72 6e 65  n can be returne
2e1f0 64 20 61 73 0a 2a 2a 20 65 69 74 68 65 72 20 61  d as.** either a
2e200 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
2e210 20 73 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 5f   string.  ^The _
2e220 64 61 74 61 62 61 73 65 5f 20 72 6f 75 74 69 6e  database_ routin
2e230 65 73 20 72 65 74 75 72 6e 0a 2a 2a 20 74 68 65  es return.** the
2e240 20 64 61 74 61 62 61 73 65 20 6e 61 6d 65 2c 20   database name, 
2e250 74 68 65 20 5f 74 61 62 6c 65 5f 20 72 6f 75 74  the _table_ rout
2e260 69 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20  ines return the 
2e270 74 61 62 6c 65 20 6e 61 6d 65 2c 20 61 6e 64 0a  table name, and.
2e280 2a 2a 20 74 68 65 20 6f 72 69 67 69 6e 5f 20 72  ** the origin_ r
2e290 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 74  outines return t
2e2a0 68 65 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65 2e 0a  he column name..
2e2b0 2a 2a 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  ** ^The returned
2e2c0 20 73 74 72 69 6e 67 20 69 73 20 76 61 6c 69 64   string is valid
2e2d0 20 75 6e 74 69 6c 20 74 68 65 20 5b 70 72 65 70   until the [prep
2e2e0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2e2f0 69 73 20 64 65 73 74 72 6f 79 65 64 0a 2a 2a 20  is destroyed.** 
2e300 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
2e310 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2e320 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2e330 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2e340 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2e350 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2e360 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2e370 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2e380 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2e390 72 20 75 6e 74 69 6c 20 74 68 65 20 73 61 6d 65  r until the same
2e3a0 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
2e3b0 72 65 71 75 65 73 74 65 64 0a 2a 2a 20 61 67 61  requested.** aga
2e3c0 69 6e 20 69 6e 20 61 20 64 69 66 66 65 72 65 6e  in in a differen
2e3d0 74 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 0a 2a  t encoding..**.*
2e3e0 2a 20 5e 54 68 65 20 6e 61 6d 65 73 20 72 65 74  * ^The names ret
2e3f0 75 72 6e 65 64 20 61 72 65 20 74 68 65 20 6f 72  urned are the or
2e400 69 67 69 6e 61 6c 20 75 6e 2d 61 6c 69 61 73 65  iginal un-aliase
2e410 64 20 6e 61 6d 65 73 20 6f 66 20 74 68 65 0a 2a  d names of the.*
2e420 2a 20 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c  * database, tabl
2e430 65 2c 20 61 6e 64 20 63 6f 6c 75 6d 6e 2e 0a 2a  e, and column..*
2e440 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
2e450 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 73  argument to thes
2e460 65 20 69 6e 74 65 72 66 61 63 65 73 20 69 73 20  e interfaces is 
2e470 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2e480 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 54 68 65 73  ement]..** ^Thes
2e490 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2e4a0 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61  rn information a
2e4b0 62 6f 75 74 20 74 68 65 20 4e 74 68 20 72 65 73  bout the Nth res
2e4c0 75 6c 74 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  ult column retur
2e4d0 6e 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 73 74  ned by.** the st
2e4e0 61 74 65 6d 65 6e 74 2c 20 77 68 65 72 65 20 4e  atement, where N
2e4f0 20 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 66   is the second f
2e500 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
2e510 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 2d 6d  ..** ^The left-m
2e520 6f 73 74 20 63 6f 6c 75 6d 6e 20 69 73 20 63 6f  ost column is co
2e530 6c 75 6d 6e 20 30 20 66 6f 72 20 74 68 65 73 65  lumn 0 for these
2e540 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
2e550 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
2e560 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 20  umn returned by 
2e570 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2e580 20 61 6e 20 65 78 70 72 65 73 73 69 6f 6e 20 6f   an expression o
2e590 72 0a 2a 2a 20 73 75 62 71 75 65 72 79 20 61 6e  r.** subquery an
2e5a0 64 20 69 73 20 6e 6f 74 20 61 20 63 6f 6c 75 6d  d is not a colum
2e5b0 6e 20 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 6c  n value, then al
2e5c0 6c 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  l of these funct
2e5d0 69 6f 6e 73 20 72 65 74 75 72 6e 0a 2a 2a 20 4e  ions return.** N
2e5e0 55 4c 4c 2e 20 20 5e 54 68 65 73 65 20 72 6f 75  ULL.  ^These rou
2e5f0 74 69 6e 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  tine might also 
2e600 72 65 74 75 72 6e 20 4e 55 4c 4c 20 69 66 20 61  return NULL if a
2e610 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2e620 6f 6e 20 65 72 72 6f 72 0a 2a 2a 20 6f 63 63 75  on error.** occu
2e630 72 73 2e 20 20 5e 4f 74 68 65 72 77 69 73 65 2c  rs.  ^Otherwise,
2e640 20 74 68 65 79 20 72 65 74 75 72 6e 20 74 68 65   they return the
2e650 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 61 74 74   name of the att
2e660 61 63 68 65 64 20 64 61 74 61 62 61 73 65 2c 20  ached database, 
2e670 74 61 62 6c 65 2c 0a 2a 2a 20 6f 72 20 63 6f 6c  table,.** or col
2e680 75 6d 6e 20 74 68 61 74 20 71 75 65 72 79 20 72  umn that query r
2e690 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 77 61 73  esult column was
2e6a0 20 65 78 74 72 61 63 74 65 64 20 66 72 6f 6d 2e   extracted from.
2e6b0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 77 69 74 68 20  .**.** ^As with 
2e6c0 61 6c 6c 20 6f 74 68 65 72 20 53 51 4c 69 74 65  all other SQLite
2e6d0 20 41 50 49 73 2c 20 74 68 6f 73 65 20 77 68 6f   APIs, those who
2e6e0 73 65 20 6e 61 6d 65 73 20 65 6e 64 20 77 69 74  se names end wit
2e6f0 68 20 22 31 36 22 20 72 65 74 75 72 6e 0a 2a 2a  h "16" return.**
2e700 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
2e710 73 74 72 69 6e 67 73 20 61 6e 64 20 74 68 65 20  strings and the 
2e720 6f 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 73 20  other functions 
2e730 72 65 74 75 72 6e 20 55 54 46 2d 38 2e 0a 2a 2a  return UTF-8..**
2e740 0a 2a 2a 20 5e 54 68 65 73 65 20 41 50 49 73 20  .** ^These APIs 
2e750 61 72 65 20 6f 6e 6c 79 20 61 76 61 69 6c 61 62  are only availab
2e760 6c 65 20 69 66 20 74 68 65 20 6c 69 62 72 61 72  le if the librar
2e770 79 20 77 61 73 20 63 6f 6d 70 69 6c 65 64 20 77  y was compiled w
2e780 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
2e790 54 45 5f 45 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e  TE_ENABLE_COLUMN
2e7a0 5f 4d 45 54 41 44 41 54 41 5d 20 43 2d 70 72 65  _METADATA] C-pre
2e7b0 70 72 6f 63 65 73 73 6f 72 20 73 79 6d 62 6f 6c  processor symbol
2e7c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2e7d0 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2e7e0 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20  all one or more 
2e7f0 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2e800 73 20 61 67 61 69 6e 73 74 20 74 68 65 20 73 61  s against the sa
2e810 6d 65 0a 2a 2a 20 70 72 65 70 61 72 65 64 20 73  me.** prepared s
2e820 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 63 6f 6c  tatement and col
2e830 75 6d 6e 20 61 74 20 74 68 65 20 73 61 6d 65 20  umn at the same 
2e840 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2e850 73 75 6c 74 73 20 61 72 65 0a 2a 2a 20 75 6e 64  sults are.** und
2e860 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66  efined..**.** If
2e870 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
2e880 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
2e890 20 6d 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65   more.** [sqlite
2e8a0 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2e8b0 65 5f 6e 61 6d 65 20 7c 20 63 6f 6c 75 6d 6e 20  e_name | column 
2e8c0 6d 65 74 61 64 61 74 61 20 69 6e 74 65 72 66 61  metadata interfa
2e8d0 63 65 73 5d 0a 2a 2a 20 66 6f 72 20 74 68 65 20  ces].** for the 
2e8e0 73 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73  same [prepared s
2e8f0 74 61 74 65 6d 65 6e 74 5d 20 61 6e 64 20 72 65  tatement] and re
2e900 73 75 6c 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61  sult column.** a
2e910 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
2e920 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
2e930 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2e940 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f  */.SQLITE_API co
2e950 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2e960 33 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73  3_column_databas
2e970 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  e_name(sqlite3_s
2e980 74 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54  tmt*,int);.SQLIT
2e990 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64  E_API const void
2e9a0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2e9b0 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
2e9c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2e9d0 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  nt);.SQLITE_API 
2e9e0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2e9f0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2ea00 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2ea10 6d 74 2a 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45  mt*,int);.SQLITE
2ea20 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
2ea30 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ea40 74 61 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c  table_name16(sql
2ea50 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
2ea60 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73  .SQLITE_API cons
2ea70 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2ea80 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2ea90 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2eaa0 2c 69 6e 74 29 3b 0a 53 51 4c 49 54 45 5f 41 50  ,int);.SQLITE_AP
2eab0 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
2eac0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69  lite3_column_ori
2ead0 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  gin_name16(sqlit
2eae0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 0a  e3_stmt*,int);..
2eaf0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2eb00 44 65 63 6c 61 72 65 64 20 44 61 74 61 74 79 70  Declared Datatyp
2eb10 65 20 4f 66 20 41 20 51 75 65 72 79 20 52 65 73  e Of A Query Res
2eb20 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  ult.**.** ^(The 
2eb30 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
2eb40 69 73 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  is a [prepared s
2eb50 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 49 66  tatement]..** If
2eb60 20 74 68 69 73 20 73 74 61 74 65 6d 65 6e 74 20   this statement 
2eb70 69 73 20 61 20 5b 53 45 4c 45 43 54 5d 20 73 74  is a [SELECT] st
2eb80 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 68 65 20  atement and the 
2eb90 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  Nth column of th
2eba0 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 72 65  e.** returned re
2ebb0 73 75 6c 74 20 73 65 74 20 6f 66 20 74 68 61 74  sult set of that
2ebc0 20 5b 53 45 4c 45 43 54 5d 20 69 73 20 61 20 74   [SELECT] is a t
2ebd0 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28 6e 6f 74  able column (not
2ebe0 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f   an.** expressio
2ebf0 6e 20 6f 72 20 73 75 62 71 75 65 72 79 29 20 74  n or subquery) t
2ec00 68 65 6e 20 74 68 65 20 64 65 63 6c 61 72 65 64  hen the declared
2ec10 20 74 79 70 65 20 6f 66 20 74 68 65 20 74 61 62   type of the tab
2ec20 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 73 20  le.** column is 
2ec30 72 65 74 75 72 6e 65 64 2e 29 5e 20 20 5e 49 66  returned.)^  ^If
2ec40 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2ec50 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73 65  of the result se
2ec60 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78 70 72 65  t is an.** expre
2ec70 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
2ec80 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c 4c 20 70  y, then a NULL p
2ec90 6f 69 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e  ointer is return
2eca0 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  ed..** ^The retu
2ecb0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20 61  rned string is a
2ecc0 6c 77 61 79 73 20 55 54 46 2d 38 20 65 6e 63 6f  lways UTF-8 enco
2ecd0 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 46 6f 72  ded..**.** ^(For
2ece0 20 65 78 61 6d 70 6c 65 2c 20 67 69 76 65 6e 20   example, given 
2ecf0 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  the database sch
2ed00 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52 45 41 54  ema:.**.** CREAT
2ed10 45 20 54 41 42 4c 45 20 74 31 28 63 31 20 56 41  E TABLE t1(c1 VA
2ed20 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a 20 61 6e  RIANT);.**.** an
2ed30 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  d the following 
2ed40 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
2ed50 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a 2a 2a 20  compiled:.**.** 
2ed60 53 45 4c 45 43 54 20 63 31 20 2b 20 31 2c 20 63  SELECT c1 + 1, c
2ed70 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a 0a 2a 2a  1 FROM t1;.**.**
2ed80 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 6f   this routine wo
2ed90 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20 73  uld return the s
2eda0 74 72 69 6e 67 20 22 56 41 52 49 41 4e 54 22 20  tring "VARIANT" 
2edb0 66 6f 72 20 74 68 65 20 73 65 63 6f 6e 64 20 72  for the second r
2edc0 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  esult.** column 
2edd0 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61 20 4e 55  (i==1), and a NU
2ede0 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  LL pointer for t
2edf0 68 65 20 66 69 72 73 74 20 72 65 73 75 6c 74 20  he first result 
2ee00 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29 2e 29 5e  column (i==0).)^
2ee10 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
2ee20 73 65 73 20 64 79 6e 61 6d 69 63 20 72 75 6e 2d  ses dynamic run-
2ee30 74 69 6d 65 20 74 79 70 69 6e 67 2e 20 20 5e 53  time typing.  ^S
2ee40 6f 20 6a 75 73 74 20 62 65 63 61 75 73 65 20 61  o just because a
2ee50 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 64 65   column.** is de
2ee60 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e 74 61 69  clared to contai
2ee70 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 74  n a particular t
2ee80 79 70 65 20 64 6f 65 73 20 6e 6f 74 20 6d 65 61  ype does not mea
2ee90 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 64 61  n that the.** da
2eea0 74 61 20 73 74 6f 72 65 64 20 69 6e 20 74 68 61  ta stored in tha
2eeb0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f 66 20 74  t column is of t
2eec0 68 65 20 64 65 63 6c 61 72 65 64 20 74 79 70 65  he declared type
2eed0 2e 20 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20  .  SQLite is.** 
2eee0 73 74 72 6f 6e 67 6c 79 20 74 79 70 65 64 2c 20  strongly typed, 
2eef0 62 75 74 20 74 68 65 20 74 79 70 69 6e 67 20 69  but the typing i
2ef00 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74 20 73 74  s dynamic not st
2ef10 61 74 69 63 2e 20 20 5e 54 79 70 65 0a 2a 2a 20  atic.  ^Type.** 
2ef20 69 73 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  is associated wi
2ef30 74 68 20 69 6e 64 69 76 69 64 75 61 6c 20 76 61  th individual va
2ef40 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74 68 20 74  lues, not with t
2ef50 68 65 20 63 6f 6e 74 61 69 6e 65 72 73 0a 2a 2a  he containers.**
2ef60 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 74 68   used to hold th
2ef70 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a 2f 0a 53  ose values..*/.S
2ef80 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20  QLITE_API const 
2ef90 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2efa0 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 28 73 71  lumn_decltype(sq
2efb0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2efc0 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e  ;.SQLITE_API con
2efd0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2efe0 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
2eff0 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2f000 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2f010 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
2f020 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
2f030 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
2f040 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2f050 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
2f060 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
2f070 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
2f080 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2f090 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f0a0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
2f0b0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
2f0c0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
2f0d0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
2f0e0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2f0f0 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
2f100 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
2f110 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
2f120 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
2f130 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
2f140 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
2f150 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
2f160 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
2f170 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2f180 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
2f190 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
2f1a0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
2f1b0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
2f1c0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
2f1d0 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
2f1e0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2f1f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
2f200 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2f210 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
2f220 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
2f230 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2f240 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2f250 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
2f260 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
2f270 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
2f280 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2f290 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
2f2a0 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
2f2b0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
2f2c0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
2f2d0 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
2f2e0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
2f2f0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2f300 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
2f310 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
2f320 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
2f330 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
2f340 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
2f350 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
2f360 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
2f370 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
2f380 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
2f390 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
2f3a0 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
2f3b0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
2f3c0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
2f3d0 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
2f3e0 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
2f3f0 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
2f400 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
2f410 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
2f420 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
2f430 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
2f440 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
2f450 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
2f460 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
2f470 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
2f480 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
2f490 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
2f4a0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
2f4b0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
2f4c0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
2f4d0 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
2f4e0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
2f4f0 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
2f500 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
2f510 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69  in an.** explici
2f520 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68  t transaction th
2f530 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f  en you should ro
2f540 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73  llback the trans
2f550 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a  action before.**
2f560 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a   continuing..**.
2f570 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  ** ^[SQLITE_DONE
2f580 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2f590 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66   statement has f
2f5a0 69 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e  inished executin
2f5b0 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c  g.** successfull
2f5c0 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70  y.  sqlite3_step
2f5d0 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65  () should not be
2f5e0 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e   called again on
2f5f0 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a   this virtual.**
2f600 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74   machine without
2f610 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b   first calling [
2f620 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2f630 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69   to reset the vi
2f640 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65  rtual.** machine
2f650 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69   back to its ini
2f660 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a  tial state..**.*
2f670 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74  * ^If the SQL st
2f680 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78  atement being ex
2f690 65 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61  ecuted returns a
2f6a0 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53  ny data, then [S
2f6b0 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73  QLITE_ROW].** is
2f6c0 20 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74   returned each t
2f6d0 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66  ime a new row of
2f6e0 20 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66   data is ready f
2f6f0 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79  or processing by
2f700 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20   the.** caller. 
2f710 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62  The values may b
2f720 65 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67  e accessed using
2f730 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63   the [column acc
2f740 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a  ess functions]..
2f750 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  ** sqlite3_step(
2f760 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69  ) is called agai
2f770 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68  n to retrieve th
2f780 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61  e next row of da
2f790 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49  ta..**.** ^[SQLI
2f7a0 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20  TE_ERROR] means 
2f7b0 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20  that a run-time 
2f7c0 65 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61  error (such as a
2f7d0 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76   constraint.** v
2f7e0 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63  iolation) has oc
2f7f0 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33  curred.  sqlite3
2f800 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e  _step() should n
2f810 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61  ot be called aga
2f820 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e  in on.** the VM.
2f830 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f   More informatio
2f840 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62  n may be found b
2f850 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
2f860 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a  e3_errmsg()]..**
2f870 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63   ^With the legac
2f880 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d  y interface, a m
2f890 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72  ore specific err
2f8a0 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61  or code (for exa
2f8b0 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  mple,.** [SQLITE
2f8c0 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51  _INTERRUPT], [SQ
2f8d0 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53  LITE_SCHEMA], [S
2f8e0 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20  QLITE_CORRUPT], 
2f8f0 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a  and so forth).**
2f900 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64   can be obtained
2f910 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2f920 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e  ite3_reset()] on
2f930 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2f940 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e  d statement].  ^
2f950 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  In the "v2" inte
2f960 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f  rface,.** the mo
2f970 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2f980 72 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e  r code is return
2f990 65 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73  ed directly by s
2f9a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a  qlite3_step()..*
2f9b0 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53  *.** [SQLITE_MIS
2f9c0 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USE] means that 
2f9d0 74 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  the this routine
2f9e0 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70   was called inap
2f9f0 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20  propriately..** 
2fa00 50 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63  Perhaps it was c
2fa10 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70  alled on a [prep
2fa20 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fa30 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65  that has.** alre
2fa40 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65  ady been [sqlite
2fa50 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2fa60 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e  alized] or on on
2fa70 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72  e that had.** pr
2fa80 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65  eviously returne
2fa90 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  d [SQLITE_ERROR]
2faa0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
2fab0 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a  ].  Or it could.
2fac0 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74  ** be the case t
2fad0 68 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74  hat the same dat
2fae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2faf0 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62   is being used b
2fb00 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65  y two or.** more
2fb10 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20   threads at the 
2fb20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74  same moment in t
2fb30 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61  ime..**.** For a
2fb40 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  ll versions of S
2fb50 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20  QLite up to and 
2fb60 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33  including 3.6.23
2fb70 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a  .1, a call to.**
2fb80 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2fb90 29 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20  )] was required 
2fba0 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74  after sqlite3_st
2fbb0 65 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e  ep() returned an
2fbc0 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20  ything.** other 
2fbd0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57  than [SQLITE_ROW
2fbe0 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62  ] before any sub
2fbf0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
2fc00 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33  on of.** sqlite3
2fc10 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72  _step().  Failur
2fc20 65 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70  e to reset the p
2fc30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fc40 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  t using .** [sql
2fc50 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f  ite3_reset()] wo
2fc60 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e  uld result in an
2fc70 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
2fc80 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20   return from.** 
2fc90 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20  sqlite3_step(). 
2fca0 20 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69   But after versi
2fcb0 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c  on 3.6.23.1, sql
2fcc0 69 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61  ite3_step() bega
2fcd0 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71  n.** calling [sq
2fce0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61  lite3_reset()] a
2fcf0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20  utomatically in 
2fd00 74 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63  this circumstanc
2fd10 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e  e rather.** than
2fd20 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49   returning [SQLI
2fd30 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69  TE_MISUSE].  Thi
2fd40 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65  s is not conside
2fd50 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c  red a compatibil
2fd60 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63  ity.** break bec
2fd70 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61  ause any applica
2fd80 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72  tion that ever r
2fd90 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54  eceives an SQLIT
2fda0 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a  E_MISUSE error.*
2fdb0 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64  * is broken by d
2fdc0 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20  efinition.  The 
2fdd0 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
2fde0 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d  ORESET] compile-
2fdf0 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63  time option.** c
2fe00 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65  an be used to re
2fe10 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79  store the legacy
2fe20 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a   behavior..**.**
2fe30 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66   <b>Goofy Interf
2fe40 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49  ace Alert:</b> I
2fe50 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74  n the legacy int
2fe60 65 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69  erface, the sqli
2fe70 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50  te3_step().** AP
2fe80 49 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73  I always returns
2fe90 20 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72   a generic error
2fea0 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45   code, [SQLITE_E
2feb0 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67  RROR], following
2fec0 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74   any.** error ot
2fed0 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
2fee0 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49  _BUSY] and [SQLI
2fef0 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75  TE_MISUSE].  You
2ff00 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73   must call.** [s
2ff10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2ff20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2ff30 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72  lize()] in order
2ff40 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20   to find one of 
2ff50 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20  the.** specific 
2ff60 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68  [error codes] th
2ff70 61 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69  at better descri
2ff80 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a  bes the error..*
2ff90 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20  * We admit that 
2ffa0 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20  this is a goofy 
2ffb0 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f  design.  The pro
2ffc0 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69  blem has been fi
2ffd0 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  xed.** with the 
2ffe0 22 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20  "v2" interface. 
2fff0 20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20   If you prepare 
30000 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20  all of your SQL 
30010 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73  statements.** us
30020 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69  ing either [sqli
30030 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
30040 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72  ] or [sqlite3_pr
30050 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e  epare16_v2()] in
30060 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20  stead.** of the 
30070 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f  legacy [sqlite3_
30080 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b  prepare()] and [
30090 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
300a0 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c  6()] interfaces,
300b0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72  .** then the mor
300c0 65 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f  e specific [erro
300d0 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74  r codes] are ret
300e0 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a  urned directly.*
300f0 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65  * by sqlite3_ste
30100 70 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66  p().  The use of
30110 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
30120 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
30130 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50  ed..*/.SQLITE_AP
30140 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74  I int sqlite3_st
30150 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ep(sqlite3_stmt*
30160 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30170 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20 63 6f  EF: Number of co
30180 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73 75 6c  lumns in a resul
30190 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  t set.**.** ^The
301a0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
301b0 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61 63 65  unt(P) interface
301c0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
301d0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
301e0 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74  n the.** current
301f0 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65 73 75   row of the resu
30200 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65 70 61  lt set of [prepa
30210 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
30220 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61 72 65  ..** ^If prepare
30230 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20 64 6f  d statement P do
30240 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65 73 75  es not have resu
30250 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72 65 74  lts ready to ret
30260 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61 6c 6c  urn.** (via call
30270 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  s to the [sqlite
30280 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c 20 73  3_column_int | s
30290 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 2a 28  qlite3_column_*(
302a0 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61  )] of.** interfa
302b0 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69 74 65  ces) then sqlite
302c0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
302d0 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20 5e 54  returns 0..** ^T
302e0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
302f0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
30300 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20 30 20   also returns 0 
30310 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c 20 70  if P is a NULL p
30320 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68 65 20  ointer..** ^The 
30330 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75  sqlite3_data_cou
30340 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20 72 65  nt(P) routine re
30350 74 75 72 6e 73 20 30 20 69 66 20 74 68 65 20 70  turns 0 if the p
30360 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 0a  revious call to.
30370 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
30380 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20 5b 53  ](P) returned [S
30390 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20 5e 54  QLITE_DONE].  ^T
303a0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
303b0 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69 6c 6c  count(P).** will
303c0 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65 72 6f   return non-zero
303d0 20 69 66 20 70 72 65 76 69 6f 75 73 20 63 61 6c   if previous cal
303e0 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74  l to [sqlite3_st
303f0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 0a  ep](P) returned.
30400 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ** [SQLITE_ROW],
30410 20 65 78 63 65 70 74 20 69 6e 20 74 68 65 20 63   except in the c
30420 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52 41 47  ase of the [PRAG
30430 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c 5f 76  MA incremental_v
30440 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72 65 20  acuum].** where 
30450 69 74 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e  it always return
30460 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65 61 63  s zero since eac
30470 68 20 73 74 65 70 20 6f 66 20 74 68 61 74 20 6d  h step of that m
30480 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70 72 61  ulti-step.** pra
30490 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20 63 6f  gma returns 0 co
304a0 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e 0a 2a  lumns of data..*
304b0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
304c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
304d0 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 53 51 4c 49 54  ount()].*/.SQLIT
304e0 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
304f0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71 6c  3_data_count(sql
30500 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
30510 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
30520 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c 20  EF: Fundamental 
30530 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45 59  Datatypes.** KEY
30540 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54 45  WORDS: SQLITE_TE
30550 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72 79  XT.**.** ^(Every
30560 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74 65   value in SQLite
30570 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76 65   has one of five
30580 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61 74   fundamental dat
30590 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  atypes:.**.** <u
305a0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  l>.** <li> 64-bi
305b0 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
305c0 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20  .** <li> 64-bit 
305d0 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70 6f  IEEE floating po
305e0 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c  int number.** <l
305f0 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69  i> string.** <li
30600 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e  > BLOB.** <li> N
30610 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  ULL.** </ul>)^.*
30620 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
30630 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20 66  ants are codes f
30640 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73 65  or each of those
30650 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f   types..**.** No
30660 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 49  te that the SQLI
30670 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e 74  TE_TEXT constant
30680 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20 69   was also used i
30690 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
306a0 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d 70   2.** for a comp
306b0 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e 74  letely different
306c0 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74 77   meaning.  Softw
306d0 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20 61  are that links a
306e0 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20 53  gainst both.** S
306f0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 20  QLite version 2 
30700 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73 69  and SQLite versi
30710 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65 20  on 3 should use 
30720 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e 6f  SQLITE3_TEXT, no
30730 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58 54  t.** SQLITE_TEXT
30740 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
30750 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a 23  ITE_INTEGER  1.#
30760 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4c  define SQLITE_FL
30770 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e 65  OAT    2.#define
30780 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20 20   SQLITE_BLOB    
30790 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
307a0 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69 66  E_NULL     5.#if
307b0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
307c0 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f 54  # undef SQLITE_T
307d0 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66 69  EXT.#else.# defi
307e0 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 20  ne SQLITE_TEXT  
307f0 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65 66     3.#endif.#def
30800 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54  ine SQLITE3_TEXT
30810 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41       3../*.** CA
30820 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20 56  PI3REF: Result V
30830 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75 65  alues From A Que
30840 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  ry.** KEYWORDS: 
30850 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66  {column access f
30860 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  unctions}.**.** 
30870 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 66  These routines f
30880 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74 20  orm the "result 
30890 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e 0a  set" interface..
308a0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
308b0 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e 66  tines return inf
308c0 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 61  ormation about a
308d0 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f   single column o
308e0 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  f the current.**
308f0 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20 61   result row of a
30900 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76 65   query.  ^In eve
30910 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72 73  ry case the firs
30920 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  t argument is a 
30930 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
30940 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
30950 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20 62  ement] that is b
30960 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20 28  eing evaluated (
30970 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d  the [sqlite3_stm
30980 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  t*].** that was 
30990 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b 73  returned from [s
309a0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
309b0 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 69  2()] or one of i
309c0 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a 20  ts variants).** 
309d0 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 61  and the second a
309e0 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
309f0 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c 75  ndex of the colu
30a00 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e 66  mn for which inf
30a10 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75  ormation.** shou
30a20 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20  ld be returned. 
30a30 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
30a40 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
30a50 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20 69  lt set has the i
30a60 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65 20  ndex 0..** ^The 
30a70 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
30a80 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  s in the result 
30a90 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65  can be determine
30aa0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
30ab0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
30ac0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  ()]..**.** If th
30ad0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
30ae0 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  does not current
30af0 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76 61  ly point to a va
30b00 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20 74  lid row, or if t
30b10 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64  he.** column ind
30b20 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e  ex is out of ran
30b30 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20 69  ge, the result i
30b40 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20  s undefined..** 
30b50 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
30b60 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65  ay only be calle
30b70 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74 20  d when the most 
30b80 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  recent call to.*
30b90 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
30ba0 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 20  )] has returned 
30bb0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e 64  [SQLITE_ROW] and
30bc0 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c   neither.** [sql
30bd0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e 6f  ite3_reset()] no
30be0 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
30bf0 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65 6e  ize()] have been
30c00 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75 65   called subseque
30c10 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79 20  ntly..** If any 
30c20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
30c30 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66 74  s are called aft
30c40 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  er [sqlite3_rese
30c50 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  t()] or.** [sqli
30c60 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
30c70 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65  or after [sqlite
30c80 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
30c90 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74 68  turned.** someth
30ca0 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ing other than [
30cb0 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68 65  SQLITE_ROW], the
30cc0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
30cd0 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b 73  efined..** If [s
30ce0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
30cf0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
30d00 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
30d10 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61  finalize()].** a
30d20 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  re called from a
30d30 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
30d40 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20 74  d while any of t
30d50 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
30d60 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74 68   are pending, th
30d70 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  en the results a
30d80 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
30d90 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
30da0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 72  _column_type() r
30db0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
30dc0 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  he.** [SQLITE_IN
30dd0 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65  TEGER | datatype
30de0 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 69   code] for the i
30df0 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70 65  nitial data type
30e00 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75 6c  .** of the resul
30e10 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65 20  t column.  ^The 
30e20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20 69  returned value i
30e30 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
30e40 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53  _INTEGER],.** [S
30e50 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53  QLITE_FLOAT], [S
30e60 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53 51  QLITE_TEXT], [SQ
30e70 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b  LITE_BLOB], or [
30e80 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54  SQLITE_NULL].  T
30e90 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75  he value.** retu
30ea0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
30eb0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
30ec0 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75 6c   only meaningful
30ed0 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20 63   if no type.** c
30ee0 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65 20  onversions have 
30ef0 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73 63  occurred as desc
30f00 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41 66  ribed below.  Af
30f10 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76 65  ter a type conve
30f20 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76 61  rsion,.** the va
30f30 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
30f40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
30f50 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ype() is undefin
30f60 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20 76  ed.  Future.** v
30f70 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
30f80 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68 65  e may change the
30f90 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
30fa0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
30fb0 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  ().** following 
30fc0 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
30fd0 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  n..**.** ^If the
30fe0 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
30ff0 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69 6e  B or UTF-8 strin
31000 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74  g then the sqlit
31010 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
31020 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
31030 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
31040 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
31050 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
31060 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
31070 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20 73  lt is a UTF-16 s
31080 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69  tring, then sqli
31090 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
310a0 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
310b0 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
310c0 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  -8 and then retu
310d0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
310e0 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
310f0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
31100 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
31110 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
31120 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a 2a  n_bytes() uses.*
31130 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  * [sqlite3_snpri
31140 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72  ntf()] to conver
31150 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f 20  t that value to 
31160 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 61  a UTF-8 string a
31170 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  nd returns.** th
31180 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
31190 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67  s in that string
311a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
311b0 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ult is NULL, the
311c0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
311d0 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e 73  _bytes() returns
311e0 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   zero..**.** ^If
311f0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
31200 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36 20   BLOB or UTF-16 
31210 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65 20  string then the 
31220 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
31230 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75 74  ytes16().** rout
31240 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
31250 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
31260 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
31270 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
31280 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
31290 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68 65  TF-8 string, the
312a0 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  n sqlite3_column
312b0 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76 65  _bytes16() conve
312c0 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
312d0 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64 20  g to UTF-16 and 
312e0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
312f0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
31300 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
31310 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
31320 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
31330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
31340 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71  16() uses.** [sq
31350 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
31360 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61  ] to convert tha
31370 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46  t value to a UTF
31380 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20 72  -16 string and r
31390 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
313a0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
313b0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
313c0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
313d0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
313e0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
313f0 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20 7a  es16() returns z
31400 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ero..**.** ^The 
31410 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20  values returned 
31420 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
31430 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20  mn_bytes()] and 
31440 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
31450 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 64  umn_bytes16()] d
31460 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74 68  o not include th
31470 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  e zero terminato
31480 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a 2a  rs at the end.**
31490 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e 20   of the string. 
314a0 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20 74   ^For clarity: t
314b0 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
314c0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
314d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
314e0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  ] and [sqlite3_c
314f0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
31500 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72 20   are the number 
31510 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20 74  of.** bytes in t
31520 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20 74  he string, not t
31530 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
31540 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
31550 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64  Strings returned
31560 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
31570 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73 71  mn_text() and sq
31580 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
31590 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20 65  t16(),.** even e
315a0 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61 72  mpty strings, ar
315b0 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65  e always zero-te
315c0 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20  rminated.  ^The 
315d0 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20  return.** value 
315e0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6c  from sqlite3_col
315f0 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20 61  umn_blob() for a
31600 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
31610 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  B is a NULL poin
31620 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
31630 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
31640 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  by [sqlite3_colu
31650 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 61  mn_value()] is a
31660 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65  n.** [unprotecte
31670 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
31680 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e 70   object.  An unp
31690 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
316a0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a 2a  _value object.**
316b0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73 65   may only be use
316c0 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f  d with [sqlite3_
316d0 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61 6e  bind_value()] an
316e0 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  d [sqlite3_resul
316f0 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49  t_value()]..** I
31700 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63 74  f the [unprotect
31710 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
31720 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  ] object returne
31730 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
31740 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
31750 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79 20   is used in any 
31760 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c 75  other way, inclu
31770 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f  ding calls.** to
31780 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20 5b   routines like [
31790 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
317a0 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  t()], [sqlite3_v
317b0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
317c0 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
317d0 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68 65  ue_bytes()], the
317e0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
317f0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
31800 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
31810 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f 6e  s attempt to con
31820 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 77  vert the value w
31830 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74 65  here appropriate
31840 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  .  ^For.** examp
31850 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65 72  le, if the inter
31860 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69  nal representati
31870 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64 20  on is FLOAT and 
31880 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a 2a  a text result.**
31890 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20 5b   is requested, [
318a0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
318b0 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74 65  ()] is used inte
318c0 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f 72  rnally to perfor
318d0 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72 73  m the.** convers
318e0 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ion automaticall
318f0 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f 77  y.  ^(The follow
31900 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69 6c  ing table detail
31910 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e  s the conversion
31920 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61 70  s.** that are ap
31930 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  plied:.**.** <bl
31940 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
31950 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
31960 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74 65  ** <tr><th> Inte
31970 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74 68  rnal<br>Type <th
31980 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e 54  > Requested<br>T
31990 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65 72  ype <th>  Conver
319a0 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c  sion.**.** <tr><
319b0 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64  td>  NULL    <td
319c0 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
319d0 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a 20   Result is 0.** 
319e0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
319f0 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20    <td>  FLOAT   
31a00 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
31a10 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  0.0.** <tr><td> 
31a20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
31a30 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65 73  TEXT    <td> Res
31a40 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
31a50 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
31a60 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20   NULL    <td>   
31a70 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73  BLOB    <td> Res
31a80 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69 6e  ult is NULL poin
31a90 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
31aa0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
31ab0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
31ac0 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
31ad0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
31ae0 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
31af0 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
31b00 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
31b10 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
31b20 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
31b30 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
31b40 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
31b50 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
31b60 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
31b70 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
31b80 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  GER   <td> Conve
31b90 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74 6f  rt from float to
31ba0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72 3e   integer.** <tr>
31bb0 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74  <td>  FLOAT   <t
31bc0 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
31bd0 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e  > ASCII renderin
31be0 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a  g of the float.*
31bf0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
31c00 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20  T   <td>   BLOB 
31c10 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20     <td> Same as 
31c20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20 3c  FLOAT->TEXT.** <
31c30 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
31c40 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
31c50 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29 0a  <td> Use atoi().
31c60 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58  ** <tr><td>  TEX
31c70 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  T    <td>  FLOAT
31c80 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f      <td> Use ato
31c90 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  f().** <tr><td> 
31ca0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 20   TEXT    <td>   
31cb0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f 20  BLOB    <td> No 
31cc0 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c 74  change.** <tr><t
31cd0 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
31ce0 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20   INTEGER   <td> 
31cf0 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54 20  Convert to TEXT 
31d00 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29 0a  then use atoi().
31d10 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f  ** <tr><td>  BLO
31d20 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54  B    <td>  FLOAT
31d30 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74      <td> Convert
31d40 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73   to TEXT then us
31d50 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e  e atof().** <tr>
31d60 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
31d70 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64  d>   TEXT    <td
31d80 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65 72  > Add a zero ter
31d90 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64 65  minator if neede
31da0 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a  d.** </table>.**
31db0 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e   </blockquote>)^
31dc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65  .**.** The table
31dd0 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65 66   above makes ref
31de0 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64 61  erence to standa
31df0 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75 6e  rd C library fun
31e00 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a 2a  ctions atoi().**
31e10 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53 51   and atof().  SQ
31e20 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72 65  Lite does not re
31e30 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20 66  ally use these f
31e40 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68 61  unctions.  It ha
31e50 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71 75  s its.** own equ
31e60 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61 6c  ivalent internal
31e70 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65 20   routines.  The 
31e80 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66 28  atoi() and atof(
31e90 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 75  ) names are.** u
31ea0 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c 65  sed in the table
31eb0 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e 64   for brevity and
31ec0 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61 72   because they ar
31ed0 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d 6f  e familiar to mo
31ee0 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d 6d  st.** C programm
31ef0 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ers..**.** Note 
31f00 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20 63  that when type c
31f10 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75 72  onversions occur
31f20 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  , pointers retur
31f30 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a 20  ned by prior.** 
31f40 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
31f50 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
31f60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
31f70 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a 2a  ext(), and/or.**
31f80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
31f90 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65 20  text16() may be 
31fa0 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 20  invalidated..** 
31fb0 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  Type conversions
31fc0 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e 76   and pointer inv
31fd0 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68 74  alidations might
31fe0 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65   occur.** in the
31ff0 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65 73   following cases
32000 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
32010 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
32020 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42 4c   content is a BL
32030 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  OB and sqlite3_c
32040 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 0a  olumn_text() or.
32050 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f  **      sqlite3_
32060 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
32070 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a 65  is called.  A ze
32080 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d 69  ro-terminator mi
32090 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65 64  ght.**      need
320a0 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f 20   to be added to 
320b0 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69 3e  the string.</li>
320c0 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69  .** <li> The ini
320d0 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20  tial content is 
320e0 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20 73  UTF-8 text and s
320f0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
32100 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20 20  tes16() or.**   
32110 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
32120 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
32130 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65  lled.  The conte
32140 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65  nt must be conve
32150 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20  rted.**      to 
32160 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20  UTF-16.</li>.** 
32170 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c  <li> The initial
32180 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d   content is UTF-
32190 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69  16 text and sqli
321a0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
321b0 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
321c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
321d0 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20  t() is called.  
321e0 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74  The content must
321f0 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a   be converted.**
32200 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e 3c        to UTF-8.<
32210 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  /li>.** </ul>.**
32220 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e 73  .** ^Conversions
32230 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36 62   between UTF-16b
32240 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20 61  e and UTF-16le a
32250 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20 69  re always done i
32260 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a 2a  n place and do.*
32270 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74 65  * not invalidate
32280 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72   a prior pointer
32290 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75 72  , though of cour
322a0 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  se the content o
322b0 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a 20  f the buffer.** 
322c0 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20 70  that the prior p
322d0 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63 65  ointer reference
322e0 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65 6e  s will have been
322f0 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68 65   modified.  Othe
32300 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63 6f  r kinds.** of co
32310 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f 6e  nversion are don
32320 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e 20  e in place when 
32330 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c 20  it is possible, 
32340 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74 68  but sometimes th
32350 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70 6f  ey.** are not po
32360 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74 68  ssible and in th
32370 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72 20  ose cases prior 
32380 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e 76  pointers are inv
32390 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  alidated..**.** 
323a0 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20 65  The safest and e
323b0 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d 62  asiest to rememb
323c0 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f 20  er policy is to 
323d0 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f 75  invoke these rou
323e0 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65 20  tines.** in one 
323f0 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  of the following
32400 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c   ways:.**.** <ul
32410 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65  >.**  <li>sqlite
32420 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20  3_column_text() 
32430 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
32440 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
32450 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e  ()</li>.**  <li>
32460 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
32470 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  lob() followed b
32480 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
32490 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
324a0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
324b0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 6f  lumn_text16() fo
324c0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
324d0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
324e0 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e  ()</li>.** </ul>
324f0 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  .**.** In other 
32500 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75 6c  words, you shoul
32510 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 63  d call sqlite3_c
32520 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a 2a  olumn_text(),.**
32530 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
32540 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69 74  blob(), or sqlit
32550 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
32560 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72 63  () first to forc
32570 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a 20  e the result.** 
32580 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65 64  into the desired
32590 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69 6e   format, then in
325a0 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  voke sqlite3_col
325b0 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a  umn_bytes() or.*
325c0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
325d0 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66 69  _bytes16() to fi
325e0 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  nd the size of t
325f0 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20 6e  he result.  Do n
32600 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a 20  ot mix calls.** 
32610 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  to sqlite3_colum
32620 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69  n_text() or sqli
32630 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
32640 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 0a  ) with calls to.
32650 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
32660 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e 64  n_bytes16(), and
32670 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c   do not mix call
32680 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  s to sqlite3_col
32690 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20  umn_text16().** 
326a0 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73 71  with calls to sq
326b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
326c0 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  es()..**.** ^The
326d0 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e   pointers return
326e0 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e 74  ed are valid unt
326f0 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72  il a type conver
32700 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a 2a  sion occurs as.*
32710 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f 76  * described abov
32720 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71 6c  e, or until [sql
32730 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20  ite3_step()] or 
32740 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
32750 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
32760 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73 20  _finalize()] is 
32770 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d 65  called.  ^The me
32780 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64 20  mory space used 
32790 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73 0a  to hold strings.
327a0 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73 20  ** and BLOBs is 
327b0 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63 61  freed automatica
327c0 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74 3c  lly.  Do <b>not<
327d0 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f 69  /b> pass the poi
327e0 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a 2a  nters returned.*
327f0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
32800 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
32810 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
32820 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
32830 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
32840 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
32850 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
32860 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
32870 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
32880 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
32890 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
328a0 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
328b0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
328c0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
328d0 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
328e0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
328f0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
32900 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
32910 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
32920 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
32930 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
32940 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
32950 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
32960 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
32970 53 51 4c 49 54 45 5f 41 50 49 20 63 6f 6e 73 74  SQLITE_API const
32980 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
32990 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
329a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
329b0 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
329c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
329d0 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33  mn_bytes(sqlite3
329e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
329f0 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  );.SQLITE_API in
32a00 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
32a10 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
32a20 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
32a30 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f  );.SQLITE_API do
32a40 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  uble sqlite3_col
32a50 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74  umn_double(sqlit
32a60 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
32a70 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ol);.SQLITE_API 
32a80 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  int sqlite3_colu
32a90 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  mn_int(sqlite3_s
32aa0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
32ab0 0a 53 51 4c 49 54 45 5f 41 50 49 20 73 71 6c 69  .SQLITE_API sqli
32ac0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
32ad0 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
32ae0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
32af0 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f  t iCol);.SQLITE_
32b00 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
32b10 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
32b20 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
32b30 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
32b40 69 43 6f 6c 29 3b 0a 53 51 4c 49 54 45 5f 41 50  iCol);.SQLITE_AP
32b50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  I const void *sq
32b60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
32b70 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
32b80 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51  *, int iCol);.SQ
32b90 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73 71 6c  LITE_API int sql
32ba0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65  ite3_column_type
32bb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
32bc0 69 6e 74 20 69 43 6f 6c 29 3b 0a 53 51 4c 49 54  int iCol);.SQLIT
32bd0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 76 61  E_API sqlite3_va
32be0 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  lue *sqlite3_col
32bf0 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  umn_value(sqlite
32c00 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
32c10 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
32c20 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50  REF: Destroy A P
32c30 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
32c40 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e  t Object.**.** ^
32c50 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  The sqlite3_fina
32c60 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  lize() function 
32c70 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c  is called to del
32c80 65 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ete a [prepared 
32c90 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
32ca0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
32cb0 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66  nt evaluation of
32cc0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65   the statement e
32cd0 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72  ncountered no er
32ce0 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68  rors.** or if th
32cf0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
32d00 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61  ever been evalua
32d10 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ted, then sqlite
32d20 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74  3_finalize() ret
32d30 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f  urns.** SQLITE_O
32d40 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  K.  ^If the most
32d50 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69   recent evaluati
32d60 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20  on of statement 
32d70 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a  S failed, then.*
32d80 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  * sqlite3_finali
32d90 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68  ze(S) returns th
32da0 65 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65  e appropriate [e
32db0 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  rror code] or.**
32dc0 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
32dd0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
32de0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
32df0 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63  ize(S) routine c
32e00 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20  an be called at 
32e10 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67  any point during
32e20 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63  .** the life cyc
32e30 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20  le of [prepared 
32e40 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a  statement] S:.**
32e50 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e   before statemen
32e60 74 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c  t S is ever eval
32e70 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20  uated, after.** 
32e80 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c  one or more call
32e90 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65  s to [sqlite3_re
32ea0 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72  set()], or after
32eb0 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20   any call.** to 
32ec0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
32ed0 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
32ee0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
32ef0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a  e statement has.
32f00 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65  ** completed exe
32f10 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49  cution..**.** ^I
32f20 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
32f30 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20  finalize() on a 
32f40 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
32f50 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  a harmless no-op
32f60 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
32f70 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e  ication must fin
32f80 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65  alize every [pre
32f90 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
32fa0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f   in order to avo
32fb0 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c  id.** resource l
32fc0 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67  eaks.  It is a g
32fd0 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f  rievous error fo
32fe0 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
32ff0 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a  n to try to use.
33000 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74  ** a prepared st
33010 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
33020 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
33030 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66  zed.  Any use of
33040 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73   a prepared.** s
33050 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69  tatement after i
33060 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
33070 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20  ized can result 
33080 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  in undefined and
33090 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20  .** undesirable 
330a0 62 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73  behavior such as
330b0 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68   segfaults and h
330c0 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a  eap corruption..
330d0 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
330e0 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  t sqlite3_finali
330f0 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ze(sqlite3_stmt 
33100 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *pStmt);../*.** 
33110 43 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20  CAPI3REF: Reset 
33120 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
33130 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
33140 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65  * The sqlite3_re
33150 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  set() function i
33160 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65  s called to rese
33170 74 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  t a [prepared st
33180 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
33190 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ct back to its i
331a0 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65  nitial state, re
331b0 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65  ady to be re-exe
331c0 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53  cuted..** ^Any S
331d0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72  QL statement var
331e0 69 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20  iables that had 
331f0 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20  values bound to 
33200 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68  them using.** th
33210 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
33220 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62  blob | sqlite3_b
33230 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74  ind_*() API] ret
33240 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73  ain their values
33250 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65  ..** Use [sqlite
33260 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73  3_clear_bindings
33270 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65  ()] to reset the
33280 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a   bindings..**.**
33290 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
332a0 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
332b0 63 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70  ce resets the [p
332c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
332d0 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20  t] S.** back to 
332e0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
332f0 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a   its program..**
33300 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
33310 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
33320 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
33330 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
33340 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33350 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51  ] S returned [SQ
33360 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51  LITE_ROW] or [SQ
33370 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f  LITE_DONE],.** o
33380 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  r if [sqlite3_st
33390 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72  ep(S)] has never
333a0 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c   before been cal
333b0 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65  led on S,.** the
333c0 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  n [sqlite3_reset
333d0 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51  (S)] returns [SQ
333e0 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20  LITE_OK]..**.** 
333f0 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
33400 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
33410 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
33420 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
33430 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
33440 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72  indicated an err
33450 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c  or, then.** [sql
33460 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72  ite3_reset(S)] r
33470 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70  eturns an approp
33480 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64  riate [error cod
33490 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  e]..**.** ^The [
334a0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29  sqlite3_reset(S)
334b0 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73  ] interface does
334c0 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
334d0 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79  values.** of any
334e0 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
334f0 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e  lob|bindings] on
33500 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
33510 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a  tatement] S..*/.
33520 53 51 4c 49 54 45 5f 41 50 49 20 69 6e 74 20 73  SQLITE_API int s
33530 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
33540 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
33550 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33560 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
33570 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
33580 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
33590 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
335a0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
335b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
335c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
335d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
335e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
335f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
33600 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
33610 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
33620 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
33630 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
33640 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
33650 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
33660 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
33670 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
33680 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
33690 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
336a0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
336b0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
336c0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
336d0 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
336e0 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
336f0 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
33700 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
33710 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
33720 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
33730 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
33740 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
33750 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
33760 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
33770 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
33780 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
33790 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
337a0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
337b0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
337c0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
337d0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
337e0 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
337f0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
33800 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
33810 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
33820 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
33830 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
33840 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
33850 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
33860 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
33870 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33880 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
33890 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
338a0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
338b0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
338c0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
338d0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
338e0 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
338f0 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
33900 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
33910 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
33920 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
33930 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
33940 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
33950 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
33960 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
33970 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
33980 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
33990 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
339a0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
339b0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
339c0 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
339d0 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
339e0 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
339f0 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
33a00 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
33a10 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
33a20 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
33a30 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
33a40 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
33a50 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
33a60 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
33a70 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
33a80 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
33a90 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
33aa0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
33ab0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
33ac0 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
33ad0 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
33ae0 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
33af0 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
33b00 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
33b10 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
33b20 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
33b30 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
33b40 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
33b50 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
33b60 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
33b70 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
33b80 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
33b90 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
33ba0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
33bb0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
33bc0 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
33bd0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
33be0 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
33bf0 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
33c00 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
33c10 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
33c20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
33c30 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
33c40 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
33c50 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
33c60 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74   Every SQL funct
33c70 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
33c80 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20  on must be able 
33c90 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20  to work.** with 
33ca0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
33cb0 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
33cc0 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
33cd0 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
33ce0 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
33cf0 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
33d00 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
33d10 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
33d20 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
33d30 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
33d40 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
33d50 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
33d60 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
33d70 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
33d80 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
33d90 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
33da0 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
33db0 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
33dc0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
33dd0 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
33de0 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
33df0 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
33e00 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
33e10 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
33e20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
33e30 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
33e40 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
33e50 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
33e60 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
33e70 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
33e80 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
33e90 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
33ea0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
33eb0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
33ec0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
33ed0 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
33ee0 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
33ef0 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
33f00 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
33f10 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
33f20 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
33f30 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
33f40 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
33f50 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
33f60 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
33f70 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
33f80 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
33f90 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
33fa0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
33fb0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
33fc0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
33fd0 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
33fe0 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
33ff0 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
34000 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
34010 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
34020 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
34030 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
34040 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
34050 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
34060 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
34070 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
34080 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
34090 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
340a0 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
340b0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
340c0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
340d0 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
340e0 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
340f0 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
34100 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
34110 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
34120 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
34130 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
34140 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
34150 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
34160 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
34170 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
34180 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
34190 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
341a0 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
341b0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
341c0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
341d0 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
341e0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
341f0 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
34200 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
34210 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
34220 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
34230 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
34240 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
34250 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
34260 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
34270 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
34280 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
34290 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
342a0 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
342b0 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
342c0 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
342d0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
342e0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
342f0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
34300 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
34310 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
34320 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
34330 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
34340 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
34350 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
34360 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
34370 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
34380 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
34390 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
343a0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
343b0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
343c0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
343d0 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
343e0 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
343f0 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
34400 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
34410 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
34420 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
34430 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
34440 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
34450 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
34460 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
34470 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
34480 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
34490 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
344a0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
344b0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
344c0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
344d0 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
344e0 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
344f0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
34500 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
34510 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
34520 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
34530 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
34540 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
34550 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
34560 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
34570 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
34580 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
34590 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
345a0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
345b0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
345c0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
345d0 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
345e0 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
345f0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
34600 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
34610 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
34620 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
34630 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
34640 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
34650 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
34660 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
34670 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
34680 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
34690 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
346a0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
346b0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
346c0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
346d0 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
346e0 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
346f0 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
34700 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
34710 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
34720 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
34730 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
34740 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
34750 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
34760 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
34770 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
34780 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
34790 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
347a0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
347b0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
347c0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
347d0 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
347e0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
347f0 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
34800 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
34810 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49 20 69 6e  */.SQLITE_API in
34820 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
34830 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c  _function(.  sql
34840 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
34850 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
34860 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
34870 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
34880 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
34890 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
348a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
348b0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
348c0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
348d0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
348e0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
348f0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
34900 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
34910 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
34920 29 0a 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49 20  ).);.SQLITE_API 
34930 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
34940 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20  te_function16(. 
34950 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20   sqlite3 *db,.  
34960 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e  const void *zFun
34970 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74  ctionName,.  int
34980 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65   nArg,.  int eTe
34990 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70  xtRep,.  void *p
349a0 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  App,.  void (*xF
349b0 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  unc)(sqlite3_con
349c0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
349d0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
349e0 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69  id (*xStep)(sqli
349f0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
34a00 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
34a10 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e  ),.  void (*xFin
34a20 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  al)(sqlite3_cont
34a30 65 78 74 2a 29 0a 29 3b 0a 53 51 4c 49 54 45 5f  ext*).);.SQLITE_
34a40 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
34a50 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
34a60 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
34a70 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
34a80 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
34a90 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
34aa0 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
34ab0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
34ac0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
34ad0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
34ae0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
34af0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
34b00 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
34b10 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
34b20 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
34b30 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
34b40 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
34b50 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
34b60 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
34b70 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
34b80 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
34b90 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
34ba0 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
34bb0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
34bc0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
34bd0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
34be0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
34bf0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
34c00 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
34c10 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
34c20 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
34c30 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
34c40 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
34c50 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
34c60 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
34c70 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
34c80 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
34c90 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
34ca0 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
34cb0 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
34cc0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
34cd0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
34ce0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
34cf0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
34d00 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
34d10 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
34d20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
34d30 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
34d40 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
34d50 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
34d60 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
34d70 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
34d80 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
34d90 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
34da0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
34db0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
34dc0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
34dd0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
34de0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
34df0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
34e00 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
34e10 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
34e20 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
34e30 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
34e40 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
34e50 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
34e60 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
34e70 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
34e80 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
34e90 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
34ea0 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
34eb0 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
34ec0 53 51 4c 49 54 45 5f 41 50 49 20 53 51 4c 49 54  SQLITE_API SQLIT
34ed0 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74  E_DEPRECATED int
34ee0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
34ef0 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  te_count(sqlite3
34f00 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51 4c 49  _context*);.SQLI
34f10 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44 45  TE_API SQLITE_DE
34f20 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
34f30 69 74 65 33 5f 65 78 70 69 72 65 64 28 73 71 6c  ite3_expired(sql
34f40 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c  ite3_stmt*);.SQL
34f50 49 54 45 5f 41 50 49 20 53 51 4c 49 54 45 5f 44  ITE_API SQLITE_D
34f60 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
34f70 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62  lite3_transfer_b
34f80 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
34f90 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73  stmt*, sqlite3_s
34fa0 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  tmt*);.SQLITE_AP
34fb0 49 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  I SQLITE_DEPRECA
34fc0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
34fd0 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28 76  global_recover(v
34fe0 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
34ff0 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
35000 45 44 20 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  ED void sqlite3_
35010 74 68 72 65 61 64 5f 63 6c 65 61 6e 75 70 28 76  thread_cleanup(v
35020 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 41 50 49  oid);.SQLITE_API
35030 20 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54   SQLITE_DEPRECAT
35040 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
35050 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
35060 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
35070 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69  3_int64,int),voi
35080 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  d*,sqlite3_int64
35090 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a  );.#endif../*.**
350a0 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69   CAPI3REF: Obtai
350b0 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f  ning SQL Functio
350c0 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75  n Parameter Valu
350d0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c  es.**.** The C-l
350e0 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e  anguage implemen
350f0 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75  tation of SQL fu
35100 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72  nctions and aggr
35110 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74  egates uses.** t
35120 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72  his set of inter
35130 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f  face routines to
35140 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72 61   access the para
35150 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a  meter values on.
35160 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  ** the function 
35170 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a  or aggregate..**
35180 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66  .** The xFunc (f
35190 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69  or scalar functi
351a0 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28 66  ons) or xStep (f
351b0 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20 70  or aggregates) p
351c0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20  arameters.** to 
351d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
351e0 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20  function()] and 
351f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
35200 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a  function16()].**
35210 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b   define callback
35220 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  s that implement
35230 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
35240 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
35250 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61  s..** The 3rd pa
35260 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65  rameter to these
35270 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e   callbacks is an
35280 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65   array of pointe
35290 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63  rs to.** [protec
352a0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
352b0 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65  e] objects.  The
352c0 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74  re is one [sqlit
352d0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
352e0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72   for.** each par
352f0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53 51  ameter to the SQ
35300 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65  L function.  The
35310 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
35320 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61  used to.** extra
35330 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74  ct values from t
35340 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
35350 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a  e] objects..**.*
35360 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
35370 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20   work only with 
35380 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
35390 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
353a0 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70  s..** Any attemp
353b0 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20 72  t to use these r
353c0 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75  outines on an [u
353d0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
353e0 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a  e3_value].** obj
353f0 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75  ect results in u
35400 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
35410 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  r..**.** ^These 
35420 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75  routines work ju
35430 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72  st like the corr
35440 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d  esponding [colum
35450 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f  n access functio
35460 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  ns].** except th
35470 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e  at  these routin
35480 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65  es take a single
35490 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
354a0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
354b0 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73  t.** pointer ins
354c0 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74  tead of a [sqlit
354d0 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65  e3_stmt*] pointe
354e0 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72  r and an integer
354f0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a   column number..
35500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35510 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28  e3_value_text16(
35520 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74 72  ) interface extr
35530 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73 74  acts a UTF-16 st
35540 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  ring.** in the n
35550 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72  ative byte-order
35560 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63   of the host mac
35570 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73  hine.  ^The.** s
35580 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
35590 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69  t16be() and sqli
355a0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
355b0 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  le() interfaces.
355c0 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d 31  ** extract UTF-1
355d0 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69 67  6 strings as big
355e0 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74  -endian and litt
355f0 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63  le-endian respec
35600 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28  tively..**.** ^(
35610 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
35620 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29  e_numeric_type()
35630 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d   interface attem
35640 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20  pts to apply.** 
35650 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79  numeric affinity
35660 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20   to the value.  
35670 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20  This means that 
35680 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a  an attempt is.**
35690 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74   made to convert
356a0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e   the value to an
356b0 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61   integer or floa
356c0 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a  ting point.  If.
356d0 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72  ** such a conver
356e0 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65  sion is possible
356f0 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66   without loss of
35700 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e   information (in
35710 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c   other.** words,
35720 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69 73   if the value is
35730 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c   a string that l
35740 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62  ooks like a numb
35750 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  er).** then the 
35760 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65  conversion is pe
35770 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77  rformed.  Otherw
35780 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f  ise no conversio
35790 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65  n occurs..** The
357a0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
357b0 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66 74   | datatype] aft
357c0 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73  er conversion is
357d0 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a   returned.)^.**.
357e0 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70 61  ** Please pay pa
357f0 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69  rticular attenti
35800 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20 74  on to the fact t
35810 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20  hat the pointer 
35820 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d  returned.** from
35830 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
35840 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65  blob()], [sqlite
35850 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
35860 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
35870 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20  value_text16()] 
35880 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74  can be invalidat
35890 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75 65  ed by a subseque
358a0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
358b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
358c0 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  es()], [sqlite3_
358d0 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d  value_bytes16()]
358e0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
358f0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
35900 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
35910 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  ext16()]..**.** 
35920 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d  These routines m
35930 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72  ust be called fr
35940 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72 65  om the same thre
35950 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c  ad as.** the SQL
35960 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73   function that s
35970 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c  upplied the [sql
35980 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72  ite3_value*] par
35990 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 53 51 4c 49  ameters..*/.SQLI
359a0 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69  TE_API const voi
359b0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
359c0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 76 61  _blob(sqlite3_va
359d0 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41 50  lue*);.SQLITE_AP
359e0 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  I int sqlite3_va
359f0 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65  lue_bytes(sqlite
35a00 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
35a10 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
35a20 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
35a30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
35a40 0a 53 51 4c 49 54 45 5f 41 50 49 20 64 6f 75 62  .SQLITE_API doub
35a50 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le sqlite3_value
35a60 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
35a70 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
35a80 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  API int sqlite3_
35a90 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
35aa0 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
35ab0 45 5f 41 50 49 20 73 71 6c 69 74 65 33 5f 69 6e  E_API sqlite3_in
35ac0 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
35ad0 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
35ae0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
35af0 41 50 49 20 63 6f 6e 73 74 20 75 6e 73 69 67 6e  API const unsign
35b00 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
35b10 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
35b20 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c  te3_value*);.SQL
35b30 49 54 45 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f  ITE_API const vo
35b40 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
35b50 65 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  e_text16(sqlite3
35b60 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45  _value*);.SQLITE
35b70 5f 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20  _API const void 
35b80 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  *sqlite3_value_t
35b90 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f  ext16le(sqlite3_
35ba0 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f  value*);.SQLITE_
35bb0 41 50 49 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  API const void *
35bc0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
35bd0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
35be0 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54 45 5f 41  alue*);.SQLITE_A
35bf0 50 49 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  PI int sqlite3_v
35c00 61 6c 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65  alue_type(sqlite
35c10 33 5f 76 61 6c 75 65 2a 29 3b 0a 53 51 4c 49 54  3_value*);.SQLIT
35c20 45 5f 41 50 49 20 69 6e 74 20 73 71 6c 69 74 65  E_API int sqlite
35c30 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
35c40 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
35c50 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
35c60 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
35c70 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
35c80 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
35c90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
35ca0 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
35cb0 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
35cc0 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
35cd0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
35ce0 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
35cf0 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
35d00 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
35d10 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
35d20 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
35d30 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
35d40 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
35d50 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
35d60 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
35d70 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
35d80 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
35d90 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
35da0 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
35db0 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
35dc0 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
35dd0 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
35de0 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
35df0 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
35e00 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
35e10 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
35e20 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
35e30 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
35e40 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
35e50 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
35e60 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
35e70 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
35e80 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
35e90 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
35ea0 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
35eb0 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
35ec0 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
35ed0 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
35ee0 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
35ef0 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
35f00 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
35f10 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
35f20 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
35f30 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
35f40 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
35f50 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
35f60 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
35f70 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
35f80 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
35f90 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
35fa0 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
35fb0 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
35fc0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
35fd0 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
35fe0 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
35ff0 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
36000 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
36010 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36020 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
36030 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
36040 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
36050 20 70 6f 69 6e 74 65 72 20 69 66 20 4e 20 69 73   pointer if N is
36060 0a 2a 2a 20 6c 65 73 73 20 74 68 61 6e 20 6f 72  .** less than or
36070 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f   equal to zero o
36080 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  r if a memory al
36090 6c 6f 63 61 74 65 20 65 72 72 6f 72 20 6f 63 63  locate error occ
360a0 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  urs..**.** ^(The
360b0 20 61 6d 6f 75 6e 74 20 6f 66 20 73 70 61 63 65   amount of space
360c0 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 73 71   allocated by sq
360d0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
360e0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 69 73 0a  context(C,N) is.
360f0 2a 2a 20 64 65 74 65 72 6d 69 6e 65 64 20 62 79  ** determined by
36100 20 74 68 65 20 4e 20 70 61 72 61 6d 65 74 65 72   the N parameter
36110 20 6f 6e 20 66 69 72 73 74 20 73 75 63 63 65 73   on first succes
36120 73 66 75 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e  sful call.  Chan
36130 67 69 6e 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75  ging the.** valu
36140 65 20 6f 66 20 4e 20 69 6e 20 73 75 62 73 65 71  e of N in subseq
36150 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
36160 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
36170 6f 6e 74 65 78 74 28 29 20 77 69 74 68 69 6e 0a  ontext() within.
36180 2a 2a 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  ** the same aggr
36190 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
361a0 6e 73 74 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74  nstance will not
361b0 20 72 65 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f   resize the memo
361c0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
361d0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
361e0 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  e automatically 
361f0 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79  frees the memory
36200 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a   allocated by .*
36210 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
36220 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68  ate_context() wh
36230 65 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65  en the aggregate
36240 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73   query concludes
36250 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73  ..**.** The firs
36260 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74  t parameter must
36270 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68   be a copy of th
36280 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  e.** [sqlite3_co
36290 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63  ntext | SQL func
362a0 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68  tion context] th
362b0 61 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20  at is the first 
362c0 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
362d0 74 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69  the xStep or xFi
362e0 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  nal callback rou
362f0 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d  tine that implem
36300 65 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61  ents the aggrega
36310 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a  te.** function..
36320 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69  **.** This routi
36330 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  ne must be calle
36340 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
36350 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a  thread in which.
36360 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65  ** the aggregate
36370 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
36380 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 53 51 4c   running..*/.SQL
36390 49 54 45 5f 41 50 49 20 76 6f 69 64 20 2a 73 71  ITE_API void *sq
363a0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
363b0 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f  context(sqlite3_
363c0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42  context*, int nB
363d0 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ytes);../*.** CA
363e0 50 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74  PI3REF: User Dat
363f0 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a  a For Functions.
36400 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
36410 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69  e3_user_data() i
36420 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
36430 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
36440 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77  e pointer that w
36450 61 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61  as the pUserData
36460 20 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20   parameter (the 
36470 35 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a  5th parameter).*
36480 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  * of the [sqlite
36490 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
364a0 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c  n()].** and [sql
364b0 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
364c0 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e  tion16()] routin
364d0 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c  es that original
364e0 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
364f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36500 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f   defined functio
36510 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f  n..**.** This ro
36520 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61  utine must be ca
36530 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
36540 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69  me thread in whi
36550 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  ch.** the applic
36560 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
36570 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
36580 67 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 41 50 49  g..*/.SQLITE_API
36590 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75   void *sqlite3_u
365a0 73 65 72 5f 64 61 74 61 28 73 71 6c 69 74 65 33  ser_data(sqlite3
365b0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a  _context*);../*.
365c0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
365d0 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
365e0 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
365f0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36600 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e  3_context_db_han
36610 64 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  dle() interface 
36620 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
36630 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
36640 20 74 6f 20 74 68 65 20 5b 64 61 74 61 62 61 73   to the [databas
36650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 74  e connection] (t
36660 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72  he 1st parameter
36670 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  ).** of the [sql
36680 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
36690 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b  tion()].** and [
366a0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
366b0 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75  unction16()] rou
366c0 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69  tines that origi
366d0 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65  nally.** registe
366e0 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74  red the applicat
366f0 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63  ion defined func
36700 74 69 6f 6e 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f  tion..*/.SQLITE_
36710 41 50 49 20 73 71 6c 69 74 65 33 20 2a 73 71 6c  API sqlite3 *sql
36720 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
36730 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63  handle(sqlite3_c
36740 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  ontext*);../*.**
36750 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
36760 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61  ion Auxiliary Da
36770 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c  ta.**.** The fol
36780 6c 6f 77 69 6e 67 20 74 77 6f 20 66 75 6e 63 74  lowing two funct
36790 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
367a0 20 62 79 20 73 63 61 6c 61 72 20 53 51 4c 20 66   by scalar SQL f
367b0 75 6e 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61  unctions to.** a
367c0 73 73 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74  ssociate metadat
367d0 61 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  a with argument 
367e0 76 61 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73  values. If the s
367f0 61 6d 65 20 76 61 6c 75 65 20 69 73 20 70 61 73  ame value is pas
36800 73 65 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70  sed to.** multip
36810 6c 65 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f  le invocations o
36820 66 20 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66  f the same SQL f
36830 75 6e 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71  unction during q
36840 75 65 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20  uery execution, 
36850 75 6e 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69  under.** some ci
36860 72 63 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20  rcumstances the 
36870 61 73 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64  associated metad
36880 61 74 61 20 6d 61 79 20 62 65 20 70 72 65 73 65  ata may be prese
36890 72 76 65 64 2e 20 54 68 69 73 20 6d 61 79 0a 2a  rved. This may.*
368a0 2a 20 62 65 20 75 73 65 64 2c 20 66 6f 72 20 65  * be used, for e
368b0 78 61 6d 70 6c 65 2c 20 74 6f 20 61 64 64 20 61  xample, to add a
368c0 20 72 65 67 75 6c 61 72 2d 65 78 70 72 65 73 73   regular-express
368d0 69 6f 6e 20 6d 61 74 63 68 69 6e 67 20 73 63 61  ion matching sca
368e0 6c 61 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e  lar.** function.
368f0 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65   The compiled ve
36900 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67  rsion of the reg
36910 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20  ular expression 
36920 69 73 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  is stored as.** 
36930 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
36940 74 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c  ted with the SQL
36950 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61 73   value passed as
36960 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
36970 72 65 73 73 69 6f 6e 0a 2a 2a 20 70 61 74 74 65  ression.** patte
36980 72 6e 2e 20 20 54 68 65 20 63 6f 6d 70 69 6c 65  rn.  The compile
36990 64 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73  d regular expres
369a0 73 69 6f 6e 20 63 61 6e 20 62 65 20 72 65 75 73  sion can be reus
369b0 65 64 20 6f 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a  ed on multiple.*
369c0 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66  * invocations of
369d0 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
369e0 6f 6e 20 73 6f 20 74 68 61 74 20 74 68 65 20 6f  on so that the o
369f0 72 69 67 69 6e 61 6c 20 70 61 74 74 65 72 6e 20  riginal pattern 
36a00 73 74 72 69 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e  string.** does n
36a10 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 72 65  ot need to be re
36a20 63 6f 6d 70 69 6c 65 64 20 6f 6e 20 65 61 63 68  compiled on each
36a30 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a   invocation..**.
36a40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36a50 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
36a60 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
36a70 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
36a80 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73   metadata.** ass
36a90 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20 73  ociated by the s
36aa0 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
36ab0 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69  ta() function wi
36ac0 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d  th the Nth argum
36ad0 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20  ent.** value to 
36ae0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
36af0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
36b00 2e 20 5e 49 66 20 6e 6f 20 6d 65 74 61 64 61 74  . ^If no metadat
36b10 61 20 68 61 73 20 62 65 65 6e 20 65 76 65 72 0a  a has been ever.
36b20 2a 2a 20 62 65 65 6e 20 73 65 74 20 66 6f 72 20  ** been set for 
36b30 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74  the Nth argument
36b40 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
36b50 2c 20 6f 72 20 69 66 20 74 68 65 20 63 6f 72 72  , or if the corr
36b60 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e  esponding.** fun
36b70 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20  ction parameter 
36b80 68 61 73 20 63 68 61 6e 67 65 64 20 73 69 6e 63  has changed sinc
36b90 65 20 74 68 65 20 6d 65 74 61 2d 64 61 74 61 20  e the meta-data 
36ba0 77 61 73 20 73 65 74 2c 0a 2a 2a 20 74 68 65 6e  was set,.** then
36bb0 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
36bc0 64 61 74 61 28 29 20 72 65 74 75 72 6e 73 20 61  data() returns a
36bd0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
36be0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
36bf0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
36c00 69 6e 74 65 72 66 61 63 65 20 73 61 76 65 73 20  interface saves 
36c10 74 68 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20  the metadata.** 
36c20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 69 74  pointed to by it
36c30 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  s 3rd parameter 
36c40 61 73 20 74 68 65 20 6d 65 74 61 64 61 74 61 20  as the metadata 
36c50 66 6f 72 20 74 68 65 20 4e 2d 74 68 0a 2a 2a 20  for the N-th.** 
36c60 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
36c70 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
36c80 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 20 53  ned function.  S
36c90 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
36ca0 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 67 65  ls to sqlite3_ge
36cb0 74 5f 61 75 78 64 61 74 61 28 29 20 6d 69 67 68  t_auxdata() migh
36cc0 74 20 72 65 74 75 72 6e 20 74 68 69 73 20 64 61  t return this da
36cd0 74 61 2c 20 69 66 20 69 74 20 68 61 73 0a 2a 2a  ta, if it has.**
36ce0 20 6e 6f 74 20 62 65 65 6e 20 64 65 73 74 72 6f   not been destro
36cf0 79 65 64 2e 0a 2a 2a 20 5e 49 66 20 69 74 20 69  yed..** ^If it i
36d00 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 53 51 4c 69  s not NULL, SQLi
36d10 74 65 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74  te will invoke t
36d20 68 65 20 64 65 73 74 72 75 63 74 6f 72 0a 2a 2a  he destructor.**
36d30 20 66 75 6e 63 74 69 6f 6e 20 67 69 76 65 6e 20   function given 
36d40 62 79 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  by the 4th param
36d50 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
36d60 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 6f 6e  set_auxdata() on
36d70 0a 2a 2a 20 74 68 65 20 6d 65 74 61 64 61 74 61  .** the metadata
36d80 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   when the corres
36d90 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f 6e  ponding function
36da0 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e 67   parameter chang
36db0 65 73 0a 2a 2a 20 6f 72 20 77 68 65 6e 20 74 68  es.** or when th
36dc0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
36dd0 63 6f 6d 70 6c 65 74 65 73 2c 20 77 68 69 63 68  completes, which
36de0 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74  ever comes first
36df0 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ..**.** SQLite i
36e00 73 20 66 72 65 65 20 74 6f 20 63 61 6c 6c 20 74  s free to call t
36e10 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 61 6e  he destructor an
36e20 64 20 64 72 6f 70 20 6d 65 74 61 64 61 74 61 20  d drop metadata 
36e30 6f 6e 20 61 6e 79 0a 2a 2a 20 70 61 72 61 6d 65  on any.** parame
36e40 74 65 72 20 6f 66 20 61 6e 79 20 66 75 6e 63 74  ter of any funct
36e50 69 6f 6e 20 61 74 20 61 6e 79 20 74 69 6d 65 2e  ion at any time.
36e60 20 20 5e 54 68 65 20 6f 6e 6c 79 20 67 75 61 72    ^The only guar
36e70 61 6e 74 65 65 20 69 73 20 74 68 61 74 0a 2a 2a  antee is that.**
36e80 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   the destructor 
36e90 77 69 6c 6c 20 62 65 20 63 61 6c 6c 65 64 20 62  will be called b
36ea0 65 66 6f 72 65 20 74 68 65 20 6d 65 74 61 64 61  efore the metada
36eb0 74 61 20 69 73 20 64 72 6f 70 70 65 64 2e 0a 2a  ta is dropped..*
36ec0 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69  *.** ^(In practi
36ed0 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20  ce, metadata is 
36ee0 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65  preserved betwee
36ef0 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73  n function calls
36f00 20 66 6f 72 0a 2a 2a 20 65 78 70 72 65 73 73 69   for.** expressi
36f10 6f 6e 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ons that are con
36f20 73 74 61 6e 74 20 61 74 20 63 6f 6d 70 69 6c 65  stant at compile
36f30 20 74 69 6d 65 2e 20 54 68 69 73 20 69 6e 63 6c   time. This incl
36f40 75 64 65 73 20 6c 69 74 65 72 61 6c 0a 2a 2a 20  udes literal.** 
36f50 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72 61  values and [para
36f60 6d 65 74 65 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a  meters].)^.**.**
36f70 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
36f80 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
36f90 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
36fa0 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
36fb0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
36fc0 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
36fd0 53 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20  SQLITE_API void 
36fe0 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  *sqlite3_get_aux
36ff0 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
37000 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 53  text*, int N);.S
37010 51 4c 49 54 45 5f 41 50 49 20 76 6f 69 64 20 73  QLITE_API void s
37020 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
37030 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
37040 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f 69 64  xt*, int N, void
37050 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f 69 64  *, void (*)(void
37060 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  *));.../*.** CAP
37070 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e 74 73  I3REF: Constants
37080 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63 69 61   Defining Specia
37090 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42 65 68  l Destructor Beh
370a0 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68 65 73  avior.**.** Thes
370b0 65 20 61 72 65 20 73 70 65 63 69 61 6c 20 76 61  e are special va
370c0 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64 65 73  lues for the des
370d0 74 72 75 63 74 6f 72 20 74 68 61 74 20 69 73 20  tructor that is 
370e0 70 61 73 73 65 64 20 69 6e 20 61 73 20 74 68 65  passed in as the
370f0 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75 6d 65  .** final argume
37100 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c  nt to routines l
37110 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ike [sqlite3_res
37120 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20 5e 49  ult_blob()].  ^I
37130 66 20 74 68 65 20 64 65 73 74 72 75 63 74 6f 72  f the destructor
37140 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69 73 20  .** argument is 
37150 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c 20 69  SQLITE_STATIC, i
37160 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  t means that the
37170 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74 65 72   content pointer
37180 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a 2a 20   is constant.** 
37190 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72 20 63  and will never c
371a0 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65 73 20  hange.  It does 
371b0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 64  not need to be d
371c0 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68 65 0a  estroyed.  ^The.
371d0 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  ** SQLITE_TRANSI
371e0 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e 73 20  ENT value means 
371f0 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  that the content
37200 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63 68 61   will likely cha
37210 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20 6e 65  nge in.** the ne
37220 61 72 20 66 75 74 75 72 65 20 61 6e 64 20 74 68  ar future and th
37230 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75 6c 64  at SQLite should
37240 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20 70 72   make its own pr
37250 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a 2a 2a  ivate copy of.**
37260 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62 65 66   the content bef
37270 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a  ore returning..*
37280 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64 65 66  *.** The typedef
37290 20 69 73 20 6e 65 63 65 73 73 61 72 79 20 74 6f   is necessary to
372a0 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70 72 6f   work around pro
372b0 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61 69 6e  blems in certain
372c0 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c 65 72  .** C++ compiler
372d0 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74 20 23  s.  See ticket #
372e0 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  2191..*/.typedef
372f0 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f   void (*sqlite3_
37300 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
37310 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65  (void*);.#define
37320 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20   SQLITE_STATIC  
37330 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65      ((sqlite3_de
37340 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29  structor_type)0)
37350 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37360 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71  TRANSIENT   ((sq
37370 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
37380 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a  _type)-1)../*.**
37390 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69   CAPI3REF: Setti
373a0 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66  ng The Result Of
373b0 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e   An SQL Function
373c0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
373d0 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62  tines are used b
373e0 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78  y the xFunc or x
373f0 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20  Final callbacks 
37400 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  that.** implemen
37410 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  t SQL functions 
37420 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20  and aggregates. 
37430 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   See.** [sqlite3
37440 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
37450 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
37460 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
37470 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64  16()].** for add
37480 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
37490 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion..**.** These
374a0 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20   functions work 
374b0 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74  very much like t
374c0 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69  he [parameter bi
374d0 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66  nding] family of
374e0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73  .** functions us
374f0 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65  ed to bind value
37500 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65  s to host parame
37510 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64  ters in prepared
37520 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
37530 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51  Refer to the [SQ
37540 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63  L parameter] doc
37550 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61  umentation for a
37560 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
37570 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ation..**.** ^Th
37580 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
37590 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  _blob() interfac
375a0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
375b0 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70  t from.** an app
375c0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
375d0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
375e0 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63  the BLOB whose c
375f0 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65  ontent is pointe
37600 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73  d.** to by the s
37610 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
37620 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62  and which is N b
37630 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20  ytes long where 
37640 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72  N is the.** thir
37650 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
37660 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37670 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
37680 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74  ) interfaces set
37690 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a   the result of.*
376a0 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
376b0 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
376c0 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20  on to be a BLOB 
376d0 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a  containing all z
376e0 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64  ero.** bytes and
376f0 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65   N bytes in size
37700 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
37710 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e   value of the 2n
37720 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a  d parameter..**.
37730 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37740 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20  result_double() 
37750 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
37760 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a  he result from.*
37770 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  * an application
37780 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
37790 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69  n to be a floati
377a0 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73  ng point value s
377b0 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69  pecified.** by i
377c0 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  ts 2nd argument.
377d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
377e0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
377f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
37800 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
37810 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75  functions.** cau
37820 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  se the implement
37830 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ed SQL function 
37840 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65  to throw an exce
37850 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74  ption..** ^SQLit
37860 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e  e uses the strin
37870 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  g pointed to by 
37880 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d  the.** 2nd param
37890 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  eter of sqlite3_
378a0 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f  result_error() o
378b0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
378c0 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73  _error16().** as
378d0 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20   the text of an 
378e0 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20  error message.  
378f0 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65  ^SQLite interpre
37900 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20  ts the error.** 
37910 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66  message string f
37920 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75  rom sqlite3_resu
37930 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54  lt_error() as UT
37940 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20  F-8. ^SQLite.** 
37950 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73  interprets the s
37960 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74  tring from sqlit
37970 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
37980 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e  6() as UTF-16 in
37990 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20   native.** byte 
379a0 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20  order.  ^If the 
379b0 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
379c0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  to sqlite3_resul
379d0 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20  t_error().** or 
379e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
379f0 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61  rror16() is nega
37a00 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
37a10 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72   takes as the er
37a20 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61  ror.** message a
37a30 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75  ll text up throu
37a40 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72  gh the first zer
37a50 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20  o character..** 
37a60 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61  ^If the third pa
37a70 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
37a80 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
37a90 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
37aa0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
37ab0 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
37ac0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
37ad0 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20  es that many.** 
37ae0 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61  bytes (not chara
37af0 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20  cters) from the 
37b00 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73  2nd parameter as
37b10 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
37b20 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  ge..** ^The sqli
37b30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37b40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
37b50 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a  esult_error16().
37b60 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65  ** routines make
37b70 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20   a private copy 
37b80 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  of the error mes
37b90 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65  sage text before
37ba0 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e  .** they return.
37bb0 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c    Hence, the cal
37bc0 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61  ling function ca
37bd0 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a  n deallocate or.
37be0 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65  ** modify the te
37bf0 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65  xt after they re
37c00 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72  turn without har
37c10 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  m..** ^The sqlit
37c20 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
37c30 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  code() function 
37c40 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f  changes the erro
37c50 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e  r code.** return
37c60 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20  ed by SQLite as 
37c70 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65  a result of an e
37c80 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69  rror in a functi
37c90 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74  on.  ^By default
37ca0 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63  ,.** the error c
37cb0 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52  ode is SQLITE_ER
37cc0 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75  ROR.  ^A subsequ
37cd0 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  ent call to sqli
37ce0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
37cf0 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
37d00 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
37d10 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72  ) resets the err
37d20 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54  or code to SQLIT
37d30 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e  E_ERROR..**.** ^
37d40 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
37d50 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28  lt_error_toobig(
37d60 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
37d70 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
37d80 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
37d90 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
37da0 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
37db0 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
37dc0 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
37dd0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
37de0 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28  ult_error_nomem(
37df0 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
37e00 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
37e10 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69  ow an.** error i
37e20 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
37e30 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
37e40 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a  on failed..**.**
37e50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
37e60 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72  sult_int() inter
37e70 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
37e80 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
37e90 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
37ea0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
37eb0 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62  n to be the 32-b
37ec0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
37ed0 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
37ee0 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
37ef0 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  ment..** ^The sq
37f00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
37f10 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  64() interface s
37f20 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
37f30 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
37f40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
37f50 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
37f60 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67  e the 64-bit sig
37f70 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
37f80 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
37f90 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
37fa0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
37fb0 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29  e3_result_null()
37fc0 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
37fd0 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
37fe0 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
37ff0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
38000 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55  unction to be NU
38010 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
38020 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
38030 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65  xt(), sqlite3_re
38040 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a  sult_text16(),.*
38050 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  * sqlite3_result
38060 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64  _text16le(), and
38070 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
38080 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72  text16be() inter
38090 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65  faces.** set the
380a0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66   return value of
380b0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
380c0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
380d0 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78  n to be.** a tex
380e0 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  t string which i
380f0 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73  s represented as
38100 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e   UTF-8, UTF-16 n
38110 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
38120 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74  ,.** UTF-16 litt
38130 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54  le endian, or UT
38140 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c  F-16 big endian,
38150 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
38160 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20  * ^SQLite takes 
38170 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20  the text result 
38180 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61  from the applica
38190 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65  tion from.** the
381a0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
381b0 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  f the sqlite3_re
381c0 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
381d0 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68  faces..** ^If th
381e0 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
381f0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
38200 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
38210 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67  rfaces.** is neg
38220 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69  ative, then SQLi
38230 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20  te takes result 
38240 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e  text from the 2n
38250 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  d parameter.** t
38260 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
38270 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
38280 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
38290 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
382a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
382b0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
382c0 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  .** is non-negat
382d0 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e  ive, then as man
382e0 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  y bytes (not cha
382f0 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20  racters) of the 
38300 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  text.** pointed 
38310 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61  to by the 2nd pa
38320 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65  rameter are take
38330 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61  n as the applica
38340 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20  tion-defined.** 
38350 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e  function result.
38360 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72    If the 3rd par
38370 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65  ameter is non-ne
38380 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a  gative, then it.
38390 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  ** must be the b
383a0 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20  yte offset into 
383b0 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65  the string where
383c0 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
383d0 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70  tor would.** app
383e0 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e  ear if the strin
383f0 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d  g where NUL term
38400 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20  inated.  If any 
38410 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f  NUL characters o
38420 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73  ccur.** in the s
38430 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20  tring at a byte 
38440 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c  offset that is l
38450 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c  ess than the val
38460 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a  ue of the 3rd.**
38470 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e   parameter, then
38480 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
38490 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61  tring will conta
384a0 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73  in embedded NULs
384b0 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75   and the.** resu
384c0 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
384d0 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73  s operating on s
384e0 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65  trings with embe
384f0 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
38500 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  efined..** ^If t
38510 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
38520 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
38530 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
38540 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
38550 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
38560 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
38570 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
38580 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
38590 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
385a0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
385b0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
385c0 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  B result when it
385d0 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
385e0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
385f0 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
38600 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
38610 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
38620 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
38630 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c  ces or to.** sql
38640 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
38650 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
38660 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
38670 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
38680 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
38690 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
386a0 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
386b0 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
386c0 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
386d0 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e   copy the conten
386e0 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  t of the paramet
386f0 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65  er nor call a de
38700 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
38710 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20  content.** when 
38720 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
38730 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
38740 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
38750 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
38760 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
38770 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
38780 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
38790 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
387a0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 7